plotsyntax

Back to the Entrance Main Page

Entrance Reference Manual
PLOT Syntax For Entrance Version 1.2

Some Simple Examples
Although PLOT commands can be complicated and lengthy, they can also be this short,:

PLOT
LINE
SELECT val FROM foo;

The example above will draw a line chart plotting values from column ‘val’ using default values for everything. To add labels on the x axis, a second line and specify colors, this will work:

PLOT
XLABELS, RED LINE, BLUE LINE
SELECT
dates, vals1, vals2
   FROM myTable;

Entrance PLOT statements always consist of two parts: a first part for setting up the chart, and a second part for getting data. The data part can be any MySQL SELECT command.

Be careful to make the number of chart_series-types, eg. the LINEs in the examples so far, match the number of columns in the SELECT statement. Use SKIP when you want to include a column in the SELECT statement but don’t want it plotted.

More complicated PLOT commands can specify other chart attributes using WITH. For example, you could set the scale for the y axis this way (details below):

PLOT
XLABELS, RED LINES, BLUE TRIANGLES
WITH
SCALE 0 100 25
SELECT
dates, vals1, vals2
   FROM myTable;

Complete PLOT Syntax

PLOT [chart_type]
      chart_series_type [, ...]
    [WITH]
      [SCALE [X | Y] minimum maximum increment]
      [ZEROBASED]
[[HORIZONTAL | VERTICAL] GRIDLINES]

      [TITLE [LEFT | RIGHT | CENTER] "string"]
      ...
      [NOTE [LEFT | RIGHT | CENTER] "string"]
      ...
      [COMMENT [LEFT | RIGHT | CENTER] "string"]
      ...
      [TITLE Y [LEFT | RIGHT | CENTER] "string"]
      [TITLE X [LEFT | RIGHT | CENTER] "string"]

      [FORMAT [X | Y] {AUTO | PLAIN | SCIENTIFIC | DECIMAL "format_spec"}]

      [[color_desc] [line_type] [HORIZONTAL | VERTICAL] GRIDLINES]

      [FONT font_family font_style font_size]
      [FOREGROUND color_desc]
      [BACKGROUND color_desc]

      [[NO] SIDES]
      [[NO] COLLAR]
      [[NO] YAXIS]
      [[NO] XAXIS]
      [[NO] LEGEND]

      [{COLOR | SIZE} OVERRIDE]
      [FRAME {TO FIT | left_x top_y right_x bottom_y}]
SELECT
   (MySQL select statement body);

Chart Types
By default, the chart type is LINECHART, but this can be changed to:

chart_type = LINECHART | BARCHART | AREACHART | XY | CORRELATION |
HISTOGRAM | ROTATEDBARCHART | PIE | HIGHLOWCHART |
(extended_chart_type)

Entrance LINECHARTs can mix and match lines, bars, areas, swaths and markers, so you may never need to set the chart type You do need to switch type to draw a high/low, rotated bar, pie or correlation chart.

Chart Series Types
PLOT draws a chart of data provided by the MySQL SELECT statement. The select part of a PLOT can be any MySQL select statement.   Each chart_series_type corresponds to a column in the result set generated by the SELECT part of the command.

Each chart_series_type takes the form:

    [color_desc] [marker_size] [marker_fill] marker_type [AND LINES] |
    [color_desc] [line_type] [line_width] LINE |
    [color_desc] BAR |
    [color_desc] AREA |
    [color_desc] SWATH |
    X          |
     SKIP        |
    [ALL | ONLY (n) | AUTO] XLABELS    |

[color_desc] HIGH |
[color_desc] LOW |
[color_desc] OPEN |
[color_desc] CLOSE |

     PIELABEL   |
     PIEVALUE    |

     DATALABELS [ABOVE | BELOW | LEFT | RIGHT | CENTERED|
    [color_desc] [line_type] WHENLINES |

COLOR OVERRIDE |
SIZE OVERRIDE

Colors are discussed in the "Color Descriptions" section below.

A marker_size is:   TINY | DEFAULT | [[VERY] {BIG | SMALL}]
a marker_fill is:    FILLED | UNFILLED
and a marker_type is:
BOX | CIRCLE | TRIANGLE | OTHERTRIANGLE | DIAMOND | HORTICK |
VERTICK | XSYMBOL | PLUS

Lines can be specified with a color and line_type:     DOTTED | DASHED | SOLID
and a line_width: THIN | NORMAL | [VERY] THICK

You can also specify that both markers and lines should be drawn for a given result set column using "AND LINES".

Plurals can be used for LINE, BAR or any of the marker types.

Not all series types are supported by all charts, and a bad series type is not guaranteed to trigger an error. LINECHART is guaranteed to draw any of the types in the first block of the types list, including bars, lines, areas and swaths. HIGHLOWCHART draws any of those types and adds HIGH, LOW, OPEN, and CLOSE.

X" specifies the x-series in an XY chart. "SKIP" means ignore the corresponding column in the result set.

"XLABELS" specifies the column to use for labels drawn on the x-axis in a LINECHART, and YLABELS specifies the column to use for labels drawn on the x-axis in a ROTATEDBARCHART.

The XLABELS or YLABELS column also determines which tick marks are drawn: a non-null XLABEL value causes a tick to be drawn.

ALL means draw all labels, "ONLY (n)" means draw up to n labels, and "AUTO" means make a reasonable choice about the number of labels to draw.

"DATALABELS" are labels drawn at the plot point of each data value: the top of a bar, the center of a marker, and so on.

"WHENLINES" are vertical lines drawn from top to bottom across a BARCHART or LINECHART. A non-null WHENLINE value causes a line to be drawn at the corresponding place, and, if the WHENLINE entry is a string with nonzero length, this line will also be labelled.

"PIEVALUES" and "PIELABELS" specify the values and labels in a pie chart.

Color Descriptions
A "color_desc" takes the form:
[transparency_type] [lightness] color_name

where a transparency_type is   [VERY] {TRANSPARENT | OPAQUE}
and lightness is [VERY] {DARK | LIGHT}

The color_name can be any of:

RED | GREEN | BLUE | YELLOW | CYAN | MAGENTA | WHITE | LIGHTGRAY | GRAY | DARKGRAY | BLACK | BUTTER | ORANGE | CHOCOLATE | CHAMELEON | SKYBLUE | PLUM | SCARLETRED | ALUMINUM | CHARCOAL | RGB(r,g,b) | RGB(r,g,b,a)

The colors from "BUTTER" to "CHARCOAL" are from the Tango desktop color palette. The two RGB() functions aaccept red, green, blue and alpha values in the range 0-255.

Titles, Comments and Notes
Charts can contain an unlimited number of titles comments and notes. Titles go above the chart, notes go below, and comments are in it.

All of the text in a chart is rendered using a single font, which can be specified using the FONT keyword, which takes the form:

      FONT (family) (style) (size)

"MONOSPACED", "SERIF" and "SANSSERIF" are available on all platforms as font families. Style can be "BOLD", "ITALIC" or "PLAIN". Size is the font size in points.

Title axes, "XTITLE" and "YTITLE" are drawn with their axes.

Scaling a Value Axis
The x axis and y axis scaling can be set when they are value axes. Use:

      SCALE [X | Y] (minimum) (maximum) (increment)

where minimum, maximum, and increment are numbers, eg. "5" or "1.3e92". Extremely large values (near 1.7e308) or small values (near 4.9e-324) occurring in a chart calculation will trigger an error.

The format of labels on an axis can be specified using the "FORMAT" keyword:

     FORMAT [X | Y] {AUTO | PLAIN | SCIENTIFIC | DECIMAL "(format)"}

"AUTO" is the default and causes Entrance to make (what it thinks) is a reasonable format choice. "PLAIN" specifies labels without a decimal point, "SCIENTIFIC" specifies scientific notation, and "DECIMAL" can be used to format strings on the axis using a format string (see the Java DecimalFormat class for the details).

"ZEROBASED" causes value axes in the chart to include zero in their ranges.

Setting the Chart Frame
By default, charts resize themselves to fit the space available on the chart tab or printer page. This can be changed using the "FRAME" keyword:

      [FRAME {TO FIT | (left x) (top y) (right x) (bottom y)}]

Scrollbars appear when a frame is specified that is larger than the available space in "Charts" tab.

Color and Size Overrides
A result set column can be used to "override" the color or size setting specified in a chart series type for certain charts. This is what makes Entrance "data painting" possible.

For example, with this PLOT command:

       PLOT XY
           RED TRIANGLE, COLOR OVERRIDE
       SELECT val, colors FROM foo;

and these values in table foo:

        val                colors
        -----------       ----------------
        1.0                null
        2.0                'green'
        3.0                'blue'

a red triangle will be drawn at 1.0, a green triangle at 2.0, and a blue triangle at 3.0.

Other Chart Settings
“BARWIDTH (width)” sets the value for bar widths, 0.0 to 1.0. A value of 1.0 causes bars be drawn next to each other, 0.5 causes them to consume have the space available to them and so on.

“[NO] OUTLINE” determines whether outlines are drawn on bars.

"LEGEND" causes a legend to be displayed below the chart.

"GRIDLINES" specifies drawing horizontal or vertical grid lines.

The "FOREGROUND" color will be used for drawing text and axis lines and labels. The "BACKGROUND" color can also be specified.

"NO SIDES" turns off the top and right hand side of some charts.
“NO XAXIS” turns off the x axis
“NO YAXIS” turns off the y axis

"COLLAR" causes a margin of space to be left on the scales around data ponts.

Changes for Version 1.2, 12-2-07

OUTLINE ON/OFF has changed to [NO] OUTLINE

Added support for:
ROTATEDBARCHART and HIGHLOWCHART chart types
AREA and SWATH series types
DATALABEL alignments
COMMENTS

NO XAXIS, NO YAXIS added
YLABELS added

Problems
We need a better "PAGE" model

We need OUTLINE on or off for markers.

Pie slice explode is still missing.

MySQL is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Copyright (c) Tod Landis 2007 All Rights Reserved                           Modified: May 30, 2007