JClass Chart

PreviousNextIndex

4

Bean Reference

Choosing the Right Bean  Standard Bean Properties  Data-Loading Methods

This chapter is a reference for JClass Chart Beans and their properties. For basic Bean concepts and a tutorial, see the SimpleChart Bean Tutorial, in Chapter 3.

4.1 Choosing the Right Bean

When creating new applications in an IDE, you can use MultiChart, SimpleChart, or one of the data-binding Beans. Unless you are binding to a database, we recommend using MultiChart, both for learning JClass Chart's features and creating new applications.

The MultiChart Bean

MultiChart is JClass Chart's most powerful Bean. It contains a richer set of features than previous Beans, highlighting the superiority of JClass Chart as a charting application tool. Among its features are the ability to handle multiple data sources and multiple axes. For more information, see MultiChart, in Chapter 5.

SimpleChart

SimpleChart was designed for quick chart development in any IDE environment. It exposes the most commonly used charting properties, and presents them in easy-to-use property editors. SimpleChart can load data from a file or a design-time editor.

SimpleChart and the data- binding Beans share a common set of properties that are covered in this chapter. SimpleChart and the data-binding Beans only differ in how they load data. Therefore, this chapter is divided into Standard Bean Properties and Data-Loading Methods.

Data-Binding Beans

If you want to load data from a database, you will have to use one of the data-binding Beans. In order to chart data from a database, your application must be able to establish a connection, perform necessary queries on the data, and then put the data into a chartable format. This type of database connectivity is often called `data binding'.

There are data-binding Beans for JBuilder and for JClass DataSource.

Once you have set up your data handling for a specific Bean, you can then use the Standard Bean Properties to customize your chart.

4.1.1 JClass Chart Beans

The following table shows all of the available JClass Beans and their uses:

JClass Chart Bean

Description

MultiChart

The most powerful charting Bean.

  • Charts data from two data sources and plots them against multiple axes.
  • Data sources can be a file, or data entered at design- time. Also supports using Swing TableModel objects as data sources.
  • Compatible with all IDEs.

    See MultiChart, in Chapter 5, for complete details.

    • SimpleChart

    Charts data from a file or data entered at design-time. Also supports a Swing TableModel object as a data source. Compatible with all IDEs.

    DsdbChart

    Binds a chart to JClass DataSource and charts data from a database. Compatible with all IDEs and the BeanBox (requires JClass DataSource Component).

    JBdbChart

    Binds a chart to a JBuilder DataSet and charts data from a database (requires Borland JBuilder 3.0+).

    4.1.2 JClass Chart Beans and JCChart

    All JClass Chart Beans are subclasses of the main chart object, JCChart. This means that the entire JClass Chart API is available to any developer using any of the Beans.

    4.2 Standard Bean Properties

    SimpleChart and the data-binding Beans (VBdbChart, JBdbChart, and DSdbChart) have a set of standard properties that allow you to control the appearance and behavior of your charts.

    They only differ in the way they retrieve data. This section covers the standard properties. See Data-Loading Methods, in Chapter 4, for information on data management properties for the different Beans.

    4.2.1 Axis Properties

    JClass Chart Beans set up basic axis properties for you automatically, and adjust these properties to your data. You can also customize your axes with the axes property editors. You have control over the following axis properties:

    Axis Titles

    Enter X- and Y-axis titles in the xAxisTitleText and yAxisTitleText property editors:

    Annotation Method

    Set the annotation method for the axes using the xAnnotationMethod and yAnnotationMethod editors. By default, Value annotation is used for both:

    Value_Labels notation can only be added programmatically or by using HTML parameters; therefore, it is not very useful for Bean programming. The following examples show the three applicable annotation methods as applied to the X-axis:

    Axis Number Intervals

    To specify the number interval on the axes, enter the interval into the yAxisNumSpacing or xAxisNumSpacing property editors:

    Axis Range

    The axis number range is determined by the minimum and maximum values of the axes. By default, these values are set automatically, based on the available data. You can specify the range by using the xAxisMinMax and yAxisMinMax property editors. Enter the minimum value on the left of the comma, and the maximum on the right:

    Logarithmic Notation

    You can specify that one or both of the axes are logarithmic by setting the xAxisLogarithmic or yAxisLogarithmic properties to true:

    Hiding Axes

    By default, both the X- and Y-axes are displayed. You can hide them by setting the xAxisVisible or yAxisVisible properties to false. The following example hides the Y-axis:

    Showing Grids

    Display gridlines for one or both axes by setting the xAxisGridVisible or yAxisGridVisible properties to true. By default, the grids are hidden. The following example sets both axes to display gridlines:

    Axis Orientation

    Axis orientation determines how the axes are positioned on the chart. By default, the axes are positioned with the Y-axis left/vertical and the X-axis right/horizontal. Use the axis orientation custom editor to change how your axes are oriented. To launch the custom editor, click the axisOrientation property:

    The axis orientation editor will illustrate the eight combinations. Select the desired orientation and click Done.

    4.2.2 Chart Types

    By default, JClass Chart Beans use the Plot chart type to display data. To change to another type, use the chartType property editor. The following example selects the PIE type:

    Data Interpretation

    The following examples show how data is displayed by the different chart types:

    Area
    Bar
    Candle
    HiLo
    Hilo_Open_Close
    Pie
    Plot
    Scatter_Plot
    Stacking_Area
    Stacking_Bar
    Polar
    Area Radar
    Radar     		     

    4.2.3 Display Properties

    Font

    Set the size and style of text on your chart by clicking the font property:

    The font you choose will apply to all text on the chart simultaneously with the exception of the header and footer. Note that the font editor that appears in your IDE may be different from the example below. The following example sets the font to Courier, Bold, 24 point, with the BeanBox font editor:

    Note: The different font properties all work in the same way. Font affects all text on the chart area and legend. Header font affects the header, and Footer Font affects the footer.

    Foreground and Background Colors

    Click the foreground and background properties to set the foreground and background colors of your chart. A color editor will appear. By default, the colors are black foreground and light-gray background:

    Most IDEs have their own color editors that differ from the BeanBox. The following example sets the background color to red:

    3D Effects

    To add 3D effects to your chart, click the View3D property:

    This will bring up the View3DEditor. There are two main settings in the View3DEditor: depth, and combined elevation and rotation.

    You can add 3D effects either by typing a value in the editable box next to the Depth, Elevation, and Rotation settings, or by dragging the red square in the editor until it has the desired Elevation and Rotation. Then, check the Change Depth option box, and drag the red square until it has the Depth you want; alternatively, simply type in the value in the editable box next to this setting.

    The degree of depth, elevation, and rotation is displayed in numbers at the top of the editor. Click Done to set the changes:

    4.2.4 Headers and Footers

    Add a header, footer, or both with the headerText and footerText property editors. The following example sets both:

    The font characteristics of the header and footer are determined by the Header Font and Footer Font properties. See Section 4.2.3, Display Properties, for more details.

    4.2.5 Legends

    You can add a legend, position it, and select its layout. The legend is set up from information in the data source. For information on how to set up legend items in the data source, see Data Formats, in Chapter 8.

    Showing the Legend

    To show the legend, set the legendVisible property to true:

    Legend Placement

    Specify where the legend will be anchored in the chart area by selecting a compass direction from the legendAnchor property options. By default, legends are anchored on the East. The following example anchors the legend North:

    Legend Layout

    Legend items can be laid out vertically or horizontally. By default the legend has a vertical layout. To specify a horizontal layout, set the legendOrientation property to Horizontal:

    4.3 Data-Loading Methods

    This section covers the data-loading methods of SimpleChart and the data-binding Beans. For MultiChart data-loading details, see MultiChart, in Chapter 5. Select the Bean that best matches your data needs and follow the instructions on loading the data for that Bean:

    JClass Chart Bean

    Data Source & IDE Compatibility

    SimpleChart
  • Formatted file or design-time editor.
  • Also supports using a Swing TableModel object as the data source.
  • All IDEs.
    • DSdbChart
  • Data binding.
  • All IDEs (requires JClass DataSource component).
    • JBdbChart
  • Data binding.
  • Borland JBuilder 3.0+.

    • If you are using an IDE other than Borland JBuilder, and you want to connect to a database, you will have to use JClass DataSource (see below). JBuilder users may still want to use the JClass DataSource for data-binding instead of their IDE-specific solutions.

    JClass DataSource

    JClass DataSource is a full data-binding solution. It is a robust, hierarchical, multiple-platform data source that you can use to bind and query any JDBC-compatible database. It can also bind to platform-specific data solutions in JBuilder.

    JClass DataSource is available only in the JClass DesktopViews suite (which also contains JClass Chart, JClass Chart 3D, JClass Elements, JClass Field, JClass HiGrid, JClass JarMaster, JClass LiveTable, and JClass PageLayout). Visit http://www.quest.com for information and downloads.

    4.3.1 SimpleChart: Loading Data from a File

    There are two ways of loading data with the SimpleChart Bean: from a .dat file, or by entering data directly into the custom editor. Both methods are managed by the DataSourceEditor. To bring up the DataSourceEditor, click on the data property:

    The DataSource Editor will appear (see below).

    Loading Data from a .dat File

    To load data from a file, click Load data from a file, enter the name of the file in the File Location field, and click Done:

    Specify the full path of the file. The file must be pre-formatted to the JClass Chart Standard (see Data Sources). Sample data files are located in the JCLASS_HOME/examples/intro/chart2.dat directory.

    Editing the Default Data

    You can use the data provided in the editor as is, or you can modify it. To use existing data, just check the Edit data in the text area radio button, and click Done. Change data by deleting and inserting text in the area provided. Be careful to preserve the punctuation surrounding the original text:

    The chart below shows how the default data appears as a plot. Notice where the different elements are positioned. Each point on the X-axis is labelled with the names specified in the default data. The name of each series of y-values appears in the legend. The name of the data view is positioned directly above the legend.

    In order for the default data to display this way, you must first set the xAxisAnnotation property to Point_Labels, and the legendVisible property to true.

    4.3.2 SimpleChart: Using Swing TableModel Data Objects

    Your (Swing) application may have the data you want to chart contained in a Swing TableModel-type data object. You can use this object as your data source instead of using the JClass Chart built-in data sources if your IDE supports a TableModel editor.

    Use the SwingDataModel property to specify an already-created Swing TableModel object to use as the chart's data source.

    4.3.3 Data Binding in Borland JBuilder

    Binding a chart to a database in JBuilder involves adding a database connection and query functionality with JBuilder Components, and then using JBdbChart to connect to the dataset and chart the data. This section walks through these steps.

    Database connection and querying are handled by JBuilder components. Our coverage of these components is only intended as a guide. For detailed information on JBuilder database connectivity, consult your JBuilder documentation.

    Before proceeding, make sure you have:

    Step 1: Connect to a Database

    Use JBuilder's Database Bean to add a database connection. The icon is found under the Data Express tab.

    Add an instance to your frame. Then, use the connection property to specify the URL of the database that you want to use.

    Step 2: Query the Data

    To query the database, add an instance of JBuilder's QueryDataSet to your frame. This Bean is found under the Data Express tab.

    Select columns that you may want to chart with the query property editor. Each column will represent a series of data, or point labels. For example, to select all of the columns from a table named MotorVehicle_Sales, you would type a statement similar to:

    select * from MotorVehicle_Sales

    You can include all columns at this step, and then use JBdbChart to choose which ones to display later.

    Step 3: Connect the Chart to the DataSet

    With the database connection established and the query created, you can now use JBdbChart to connect to the JBuilder DataSet and chart the data. JBdbChart's data binding properties are dataSet, and DataBindingMetaData.

    Insert a JBdbChart into your frame.

    Select a query from the dataSet property's pull down menu. If the database connection and query are set up properly with JBuilder components, there should be one or more queries in the list.

    You can now select the columns and range of data that will be displayed. Columns that contain numeric data are considered `data series', and can be plotted on a chart. Columns that have non-numeric data can be used for point labels on the X-axis. Click the dataBindingConfig property to bring up the custom editor:

    This editor allows you to set the columns and the data range of the chart. Click on column names to select them (when they are highlighted, they are selected).

    The Potential series columns are numeric. The Potential point label column is non-numeric.

    You can either set the range to all data by checking the All rows box, or you can specify a range using the Start row and End Row fields.

    In order to display the point labels on the X-axis, you have to set the xAxisAnnotationMethod property to Point_Labels. For more information,
    see Section 4.2.1, Axis Properties.

    You should see your data in the design frame:

    With your connection established, you can then use the Standard Bean Properties to customize and enhance your chart. In the example above, a header, footer, axis title, legend, point labels, and 3D effects have been added.

    4.3.4 Data Binding with JClass DataSource

    The JClass DataSource manages all connection and query functionality for data binding. After establishing a connection and query with JClass DataSource, you then bind DSdbChart to JClass DataSource to chart the data.

    The JClass DataSource package contains a number of Beans used for binding to databases, including JCTreeData and JCData. This section will illustrate the process with the JCData Bean. DSdbChart uses the same method to connect to either Bean. Consult your JClass DataSource documentation for details on their features and how to use them.

    To use this solution, you require the following:

    The following steps guide you through using DSdbChart to connect to JClass DataSource. They are: connect to a database, query the data, and connect DSdbChart to the JClass DataSource.

    Step 1: Connect to a Database

    Add a JCData instance to your design area. The icon looks like this:

    Click the nodeProperties property to bring up the NodePropertiesEditor.

    This editor manages all of the connection and query settings. The first thing you have to do is set up a serialization file under the Serialization tab. This file saves information and settings about the connection. You can then proceed to set up a connection and query.

    To set up a database connection, go to the DataModel > JDBC > Connection tab, and specify the Server Name and Driver for the database you want to connect to. Test the connection. If there are error messages, consult your JClass DataSource documentation.

    When your connection is successful, you can then proceed to set up a query.

    Step 2: Query the Data

    Click the Data Model > JDBC > SQL Statement tab to show the query options:

    You can create your whole SQL query using mouse clicks. First, add a table, and then create a query by selecting columns. When you are all finished, click Set/Modify, and then Done.

    Step 3: Connect a Chart to JClass DataSource

    With your database connection established, you can then bind a chart to the data. This is done using the dataBinding and DataBindingMetaData property editors.

    First, add DSdbChart to your design area. The icon looks like this:

    Click the dataBinding property to bring up the DataBindingEditor.

    If the connection in JClass DataSource is properly established, you should see one or more data sources to select from:

    Select a source and click Done.

    You can now select the columns and range of rows to be displayed in the chart. To do this, click the DataBindingConfig property to bring up the DataBindingConfig custom editor:

    There are two lists of columns:

    In order to display the point labels on the X-axis, set the xAxisAnnotationMethod property to Point_Labels. For more information, see Section 4.2.1, Axis Properties.

    You can either set the range to all data by checking the All rows box, or you can specify a range using the Start Point and End Point fields.

    When you click Done, you should see the data displayed in the design area of the Beanbox or IDE. Your data binding is complete.

    PreviousNextIndex