[Index] [Introduction] [Installation] [Cookbook] [Package] [Component] [Chart] [Axis] [Utility] [Applet] [Servlet] [Appdx A] [Appdx B] [API]

FRAMESNO FRAMES  NO FRAMES INDEX


About The ParameterParser class

KavaChart applet and servlet behavior is defined by using a rich set of parameters. These are set in various ways, depending on whether you're using applets, servlets, or customized charts. This class provides a centralized parameter parser that handles the general parameters in a uniform way.

For programming information, consult the ParameterParser API documentation and the source code file javachart.applet.ParameterParser.

General Applet & Servlet Parameters

The following parameters are shared by the entire applet and servlet collections, and are related to general charting features. This table and those that follow use these conventions for describing the kind of argument each parameter requires:
 
Parameter Value Type Effect
titleString String Chart Title (default none) 
titleFont font Font name, size, & style for chart title (default TimesRoman, plain, 12 pt)
titleColor color color of text in Title (default black)
subTitleString String Chart Sub-Title (default none) 
subTitleFont font Font name, size, & style for chart title (default TimesRoman, plain, 12 pt)
subTitleColor color color of text in Title (default black)
labelsOn anything determines whether bar, line, pie, etc., labels will be visible
labelAngle integer the number of degrees to rotate datum labels
labelPrecision integer the number of digits of precision for datum labels
labelFormat integer deprecated - by default, servlets and applets will use the default locale to determine how numbers should be formatted. You can override this with labelFormat for compatibility with older releases of KavaChart
legendOn anything make the legend visible
legendOff anything make the legend invisible (default)
legendColor color sets the background color of a legend
legendVertical anything legend icons in vertical list (default)
legendHorizontal anything legend icons in horizontal list
legendLabelFont font Font name, size, & style for legend (default TimesRoman, plain, 12 pt)
legendLabelColor color color of text in legend (default black)
legendllX double X location of lower left legend corner (default 0.2)
legendllY double Y location of lower left legend corner (default 0.2)
iconWidth double width of legend icon (default 0.07)
iconHeight double height of legend icon (default 0.05)
iconGap double gap between icon and next legend entry (default 0.01)
plotAreaTop double top of the plotting area
plotAreaBottom double bottom of the plotting area
plotAreaRight double right side of the plotting area
plotAreaLeft double left side of the plotting area
plotAreaColor color color of plotting area background (default white)
backgroundColor color color of chart background (default white)
3D anything turns on 3D effects for this chart (default 2D)
2D anything turns on 2D effects for this chart (default 2D)
xDepth integer number of pixels of offset in X direction for 3D effect (default 15)
yDepth integer number of pixels of offset in y direction for 3D effect (default 15)
locale String KavaChart automatically localizes your charts for the locale of the Java Virtual Machine that creates the chart. For applets, this means your charts will automatically change things like month labels, number formatting, and so on, depending on whether your viewers are in, say, France, or Japan. For servlets, this means the output will be localized for your server's defaults. You can override the locale with this parameter. Valid locales include canada, canada_french, china, chinese, english, france, french, german, germany, italian, italy, japan, japanese, korea, korean, prc, simplified_chinese, taiwan, traditional_chinese, uk, and us.
delimiter String the separator character for list parameters. Default is comma (e.g. "123.432.123").
defaultFont Font A new default font for your charts. This parameter overrides the default font setting for KavaChart graphs. This parameter sets a new default for all KavaChart graphics running within the Java Virtual Machine in the current session, so you should use it cautiously. Its primary value is for settings that wish to start with consistent font usage for all charts.
backgroundImage URL or file name Charts can replace the solid background color with a GIF or JPEG image for added effect.

Axis Parameters

The following tables contain parameters for adjusting axes. Line, area, bar, and their derivatives use these parameters. Axis parameters consist of a set of parameters and an option list. The option list is contained in a separate table.

If you're modifying an X Axis (usually on the top or bottom of a chart), use xAxisParameterName instead of yAxisParameterName. X Axes are on the left and right for Horizontal Bar Type charts. Speedo and Polar charts have a single Axis, which is a Y Axis.

If you're modifying an Auxiliary Y Axis (charts that have left and right axes, for example), use auxAxisParameterName instead of yAxisParameterName.
Axis Parameter Value Type Effect
yAxisTitle string Axis title
yAxisTitleFont font Axis title font
yAxisTitleColor color Axis title color
yAxisLabelFont font use this font for axis labels
yAxisLabelColor color axis labels in this color (default black)
xAxisLabels list A comma separated list of user-defined labels for this Axis. This is only effective for certain types of chart (BarChart derivatives, LabelLineChart, Area charts) that use a LabelAxis. By default, LabelAxis is only used for X axes, although you can change this by making a minor modification to the applets.
yAxisLabelAngle integer label rotation in degrees (default 0). Note: rotations of 0 and 90 degrees will be the most readable
yAxisLabelFormat 0:default, 1:Comma, 2:European (default 0) Note: by default, charts will automatically localize formats based on the Java Virtual Machine running the chart.
yAxisLabelPrecision integer Number of digits past the decimal point to display
yAxisLineColor color axis line color (default black)
yAxisTickColor color axis tick mark color (default black)
yAxisGridColor color axis grid line color (default black)
yAxisColor color sets axis grids, ticks, lines and labels to the same color
yAxisTickLength integer number of pixels long for axis tick marks
yAxisMinTickLength integer number of pixels long for axis minor tick marks
yAxisStart double starting value on axis. By default, axes automatically determine a starting and ending value. By setting this value, you can give the axis a default minimum value. If the Axis is set to noAutoScale, this value will be used directly. Otherwise, this value may be adjusted slightly to yield better looking labels. For example, if you set yAxisStart to 0.01, the chart may decide to round the value down to 0.0 to create even axis increments.
yAxisEnd double ending value on axis. By default, axes automatically determine a starting and ending value. By setting this value, you can give the axis a default maximum value. If the Axis is set to noAutoScale, this value will be used directly. Otherwise, this value may be adjusted slightly to yield better looking labels. For example, if you set yAxisStart to 9.99, the chart may decide to round the value up to 10.0 to create even axis increments.
yAxisLabelCount integer how many labels on an axis set to noAutoScale
yAxisTickCount integer how many tick marks on an axis set to noAutoScale
yAxisMinTickCount integer how many minor tick marks on an axis set to noAutoScale
yAxisGridCount integer how many grid lines on an axis set to noAutoScale

Axis Option Lists

The following lists include various options for adjusting the look of an X or Y axis. Use these parameters in a list, like this: param name=xAxisOptions value="gridOff, tickOff, lineOn". If you're modifying an auxiliary Y axis (such as in a chart that has left and right axes), use auxAxisOptions.
 
 
yAxisOptions (xAxisOptions)  Effect
autoScale automatically create axis scale (default)
noAutoScale axis scale defined in applet parameters
rotateTitle "true" if vertical axis title should be parallel with axis
logScaling "true" if axis should use log scaling
lineOn axis line is visible (default)
lineOff axis line is invisible
tickOn major tick marks are visible (default)
tickOff major tick marks are invisible
minTickOn minor tick marks are visible
minTickOff minor tick marks are invisible (default)
labelsOn axis labels are visible (default)
labelsOff axis labels are invisible
gridOn grid lines are visible
gridOff grid lines are invisible (default)
rightAxis this axis goes on the right
topAxis this axis goes on the top
bottomAxis this axis goes on the bottom
leftAxis this axis goes on the left (default)

Dataset Specification

Datasets can vary a great deal from chart to chart. Some kinds of charts only use Y values, others use both X and Y values. Some charts use a color to represent an entire dataset (bar charts, line graphs), and some use a color for each data value (pie charts, individual bar charts). In general, every chart must define a list of numbers for Y data. Charts that don't define this data will use an internally generated fake dataset, which is pretty useless. For additional ways to define data, see the table on URL datasets.
 
 
Dataset Parameters (available datasets 0 through 39) Type Effect
dataset0xValues list comma separated list of X values for dataset 0
dataset0yValues list comma separated list of Y values for dataset 0
dataset0y2Values list comma separated list of difference values for dataset 0 hilo bars
dataset0xyValues list comma separated list of XY pairs for dataset 0
dataset0dateValues list comma separated list of date strings for dataset 0
dataset0Name string name for display in legend (default "dataset0")
dataset0Labels list comma separated labels for data items
dataset0Color color color to use for this dataset (default varies)
dataset0Colors list of colors colors to use for pie slices or bars (default varies)
dataset0Image URL image to use for this dataset's markers (default none)
dataset0LineWidth integer pixel width of plot line
dataset0LabelFont font font to use for this dataset's labels (default TimesRoman 12pt)
dataset0LabelColor color color to use for this dataset's labels (default black)
customDatasetHandler string information passed to a user-defined dataset handling method "void getMyDatasets(String str)" Note: in the case of DateAxis, this is the URL for a data file that contains columnar Date information

URL Dataset Parameters

These applets include a mechanism to retrieve data from a valid URL. If you're running applets, this URL must be on the same host the applet came from. To get around this restriction, you'll have to sign your applets and request permission using the requisite security classes.

Data URLs can be files, but more often, they point to CGIs that generate data dynamically. This mechanism lets you keep your overall chart definition unchanged while modifying the data to meet your requirements.

Applets can also use the networkInterval parameter to re-read data from the URL, updating the chart as necessary.

Servlets can substitute a file name for a URL to read data directly from the server's local hard drives. Applets can do this only if the applet is running locally, and was not served by a web server.
URL Dataset Parameters (available datasets 0 through 39) Type Effect
dataset0xURL URL URL for a file of comma separated X values for dataset 0
dataset0yURL URL URL for a file of comma separated list of Y values for dataset 0
dataset0URLLabels list comma separated labels for URLs
URLDataBlock URL URL for a file of comma separated Y values. Each line in this file is assumed to be a unique dataset.
URLXYDataRows URL URL for a file of comma separated XY pairs arranged into rows. Each row represents a single dataset, with values arranged as x1, y1, x2, y2, x3, y3... 
URLXYDataColumns URL URL for a file of comma separated XY pairs arranged into columns. This file must contain a single value as the first line of the file, specifying the number of observations (rows) in the file. The first two columns are dataset 1, the second two columns are dataset 2, etc.
networkInterval integer Number of seconds to wait before re-reading URL datasets (applets only)
customDatasetHandler string information passed to a user-defined dataset handling routine "void getMyDatasets(String str)" Note: in the case of DateAxis, this is the URL for a data file that contains columnar Date information

Date Chart Parameters

A subclass of ParameterParser, DateStreamReader, adds facilities for reading time oriented data in a locale-independent way. This subclass is used for all KavaChart applets and servlets that use time-oriented data, such as dateLineApp and dateAreaApp. This includes financial chart styles, such as finComboApp and hiLoCloseApp, which extend DateStreamReader further to refine the way these applets and servlets interpret blocks of data.

The following list contains general charting options for Time/Date X axes, such as those used for dateLineApp.class and dateAreaApp.class, as well as financial chart types like stickApp.class and hiLoCloseApp.class.
Parameter Type Effect
startData String Ignore any data earlier than this time/date. Note: this string is passed into Java's "Date" class to be translated into a machine independent time stamp. Many time-stamp formats will work. If you need to use a specific input format, see the Date Format section below.
endData String Ignore any data later than this time/date. Note: this string is passed into Java's "Date" class to be translated into a machine independent time stamp. Many time-stamp formats will work. If you need to use a specific input format, see the Date Format section below.
inputDateFormat String Use this pattern to read any incoming data. For more information on how to construct this string, see the Date Format section below.
incrementalDataURL URL A URL to poll for additional data points. Date oriented charts read initial data from the URL or file specified in "customDatasetHandler". Subsequent observations can be added to applets by polling the URL specified in this parameter. This URL will be checked each networkInterval.

Date Axis Parameters

The following list contains options for Time/Date X axes, such as those used for dateLineApp.class and dateAreaApp.class, as well as financial chart types like stickApp.class and hiLoCloseApp.class.
DateAxis Parameters Type Effect
startDate string time/date for axis starting value. Note: this string is passed into Java's "Date" class to be translated into a machine independent time stamp. Many time-stamp formats will work. If you need to use a specific input format, see the Date Format section below.
endDate string time/date for axis ending value
axisDateFormat string By default, DateAxis selects an appropriate labelling type based on your time range and your locale. Your applets will automatically use, for example, Japanese month names for browsers in Japan, and German month names for browsers in Germany. Similarly, applets might choose a yy/mm label for one locale, and mm/yy for another locale. This parameter lets you override the axis labels to use your specific formatting instructions. See the Date Format section below for more information on how to use the formatting patterns.
axisSecondaryDateFormat string Some DateAxes use a primary and secondary format to highlight important boundaries, like years or hours. This parameter lets you set the date or timestamp format for one of these boundaries. See the Date Format section below for more information on how to use the formatting patterns.
scalingType integer
1 scale by seconds
2 scale by minutes
3 scale by hours
4 scale by days
5 scale by weeks
6 scale by months
7 scale by years

Date Format Patterns

Time and Date oriented charts raise some interesting challenges. Input time stamps may be in a variety of languages, and a variety of formats. Axis labels might contain information as coarse as era (e.g. BC/AD) or as fine as milliseconds. Although KavaChart attempts to automate as many of these tasks as possible, you may need to fine-tune date handling by using a date format string. These strings are used in the following parameters: inputDateFormat, axisDateFormat, axisSecondaryDateFormat, and (in applets) dwellLabelDateFormat. These parameters take a pattern string like "MMM-yyyy" to specify a date format like "January-2001". Each pattern string contains the desired field specifiers along with additional text you might want to add. This table describes the available fields:
Field Full Form Short Form
Year yyyy (4 digits) yy (2 digits)
Month MMM (name) MM (2 digits), M (1 or 2 digits)
Day of week EEEE EE
Day of Month dd (2 digits) d (1 or 2 digits)
Hour (1-12) hh (2 digits) h (1 or 2 digits)
Hour (0-23) HH (2 digits) H (1 or 2 digits)
Hour (0-11) kk (2 digits) k (1 or 2 digits)
Hour (1-24) KK (2 digits) K (1 or 2 digits)
Minute mm None
Second ss None
Millisecond SSS None
AM/PM a None
Time Zone zzzz zz
Day of Week in Month F (e.g. 2nd Tuesday) None
Day in year DDD (3 digits) D (1, 2, or 3 digits)
Era G (e.g. BC or AD) None

The actual string values for each format are determined by locale and the time being formatted.
 
 


[Index] [Introduction] [Installation] [Cookbook] [Package] [Component] [Chart] [Axis] [Utility] [Applet] [Servlet] [Appdx A] [Appdx B] [API]