Scripts
Functions
The basic idea behind xmCHART is to make an extensive set of functions available to users with which the general appearance of a chart can be controlled in detail. Three functions are all you need to draw up a number of different charts: first the function OpenDrawing() defines the size of the chart, secondly the ChartData() function which contains all numerical values (or date/time values) used for representation and, thirdly, a function which determines the type of chart.
Example
Besides a comprehensive set of charting functions, xmCHART also offers numerous functions for creating geometric shapes or for adding texts, images, tables, barcodes, etc.
Examples
| | EXAMPLE_02 |
| 1 | OpenDrawing(200;100) |
| 2 | AddRect(10;10;180;80;darkYellow;solid;8;steelBlue;shaded) |
| 3 | |
| 4 | |
| 5 |
In fact, over 220 functions are available with which nearly all parts of the chart can be varied.
If a chart is to be created, all function calls — arranged as a large string of text — are transferred to xmCHART by using the external function xmCH_DrawChart() or script step Draw Chart[]. xmCHART then checks this text string for possible typing errors, missing brackets, invalid values, etc. In the event of an error, the process is aborted and an error message is sent to FileMaker Pro by xmCHART. To enable the user to quickly and easily correct this error, xmCHART sends a detailed error message, if possible, with the line number, the function name and argument index. If no errors are found, xmCHART begins to set up the chart and stores it in a FileMaker container field.
xmCHART function names and predefined constants are not case sensitive. If a function has several arguments, they are separated by semicolons (;). For example:
OPENDRAWING(800;600;PRINT)
OpenDrawing(800;600;screen)
Optional arguments can be skipped in a function call. The default values stored in xmCHART are used in this case. See Functions for these values. For example:
Literal text arguments such as label texts or filenames must be enclosed in quotation marks. For example:
LabelTexts(all;"|f1|")
AddText(20;30;"Company Universal Exports")
SaveAsPNGFile("~/desktop/img_01.png")
Quotation marks entered inside FileMaker’s Specify Calculation dialog box should be prefixed with a backslash (\"). For more details, please see Texts.
Enclosing font names in quotation marks is optional and can be omitted. For example:
AxisMajorTickLabelStyle(y;"Verdana";10;bold;darkBlue)
AxisMajorTickLabelStyle(y;Verdana;10;bold;darkBlue)
If a function is called several times, the last one will be used; all previous ones will be ignored.
Exception: The functions PieChartExplodes(),PieChartExplodeDepths() and graphics primitive functions, e.g. AddText(),AddSymbol(),AddPicture() etc. — they can be called multiple times. For example:
OpenDrawing(800;600)
ChartData(12 45 23 -10 34) /* Is ignored. */
ChartData(78 -23 56 22 11)
PieChart(shadow+label) /* Is ignored. */
FillStyle(1;red) /* Is ignored. */
AddText(20;20;"Diagram 1")
AddText(20;35;"(Variant A)")
AddText(200;280;"Copyright")
Recommended Order of Function Calls
"Global" functions, e.g. SetDecimalPoint(), SetThousandsSep(), HyphenationOptions()
DateTimeOptions() /* Before ChartData() */
ChartDataOptions() /* Before ChartData() */
Chart function, e.g. BarChart() /* After ChartaData() */
Chart function options, e.g. BarChartOptions() /* After chart function. */
Color scheme functions, e.g. FillColorScheme() /* After chart function(s). */
Style functions, e.g. FillStyle() /* After color scheme functions. */
Axis and scaling functions.
Grid, title, legend functions.
Structure
Basic Structure: OpenDrawing() . . . CloseDrawing()
Example
| | EXAMPLE_04 |
| 1 | OpenDrawing(200;100) |
| 2 | ChartData(2 9 12 6 3) |
| 3 | |
| 4 | |
| 5 | |
| 6 | AxisOptions(x;none) /* Hide x-axis. */ |
| 7 | |
| 8 | AxisMajorTicks(y;0) /* Hide y-axis tick marks. */ |
| 9 | MajorGridLineWidths(y;x;0) /* Hide vertical grid lines. */ |
| 10 | MajorGridLineWidths(x;y;0.25) |
| 11 |
OpenChart() . . . CloseChart() Structure
OpenDrawing(width;height[;resolution])
...
OpenChart(left;top;width;height[;isPlotArea])
...
sequence of xmCHART functions
...
...
OpenChart() . . . CloseChart() can be used to precisely place one or more charts on the drawing.
Examples
| | EXAMPLE_05 |
| 1 | OpenDrawing(200;100) |
| 2 | |
| 3 | ChartData(10 5 4 3 1) |
| 4 | PieChart() |
| 5 | PieChartExplodes(10;max) /* After PieChart() function. */ |
| 6 | |
| 7 | |
| 8 | |
| 9 | Background(none;;0.25;gray) |
| 10 |
| | EXAMPLE_06 |
| 1 | OpenDrawing(400;100) |
| 2 | OpenChart(10;10;180;80) |
| 3 | ChartData(2 9 12 6 3) |
| 4 | BarChart() |
| 5 | |
| 6 | BorderStyle(1;none) |
| 7 | |
| 8 | |
| 9 | AxisMajorTicks(all;0) /* Hide tick marks. */ |
| 10 | MajorGridLineWidths(y;x;0) /* Hide vertical grid lines. */ |
| 11 | MajorGridLineWidths(x;y;0.25) |
| 12 | |
| 13 | OpenChart(210;10;180;80) |
| 14 | ChartData(2 9 12 6 3) |
| 15 | |
| 16 | |
| 17 | |
| 18 | AxisOptions(x;none) /* Hide x-axis. */ |
| 19 | |
| 20 | AxisMajorTicks(y;0) /* Hide y-axis tick marks. */ |
| 21 | MajorGridLineWidths(y;x;0) /* Hide vertical grid lines. */ |
| 22 | MajorGridLineWidths(x;y;0.25) |
| 23 | |
| 24 | Background(none;;0.25;gray) |
| 25 |
The argument isPlotArea = on can be used to precisely align or overlay two or more charts.
Examples
| | EXAMPLE_07 |
| 1 | OpenDrawing(400;100) |
| 2 | |
| 3 | ChartData(2 9 12 6 3) |
| 4 | BarChart() |
| 5 | |
| 6 | BorderStyle(1;none) |
| 7 | |
| 8 | |
| 9 | AxisMajorTicks(all;0) /* Hide tick marks. */ |
| 10 | MajorGridLineWidths(y;x;0) /* Hide vertical grid lines. */ |
| 11 | MajorGridLineWidths(x;y;0.25) |
| 12 | |
| 13 | |
| 14 | ChartData(2 9 12 6 3) |
| 15 | |
| 16 | |
| 17 | |
| 18 | AxisOptions(x;none) /* Hide x-axis. */ |
| 19 | |
| 20 | AxisMajorTicks(y;0) /* Hide y-axis tick marks. */ |
| 21 | MajorGridLineWidths(y;x;0) /* Hide vertical grid lines. */ |
| 22 | MajorGridLineWidths(x;y;0.25) |
| 23 | |
| 24 | Background(none;;0.25;gray) |
| 25 |
| | EXAMPLE_08 |
| 1 | OpenDrawing(220;120) |
| 2 | |
| 3 | ChartData(2 9 12 6 3) |
| 4 | BarChart() |
| 5 | |
| 6 | BorderStyle(1;none) |
| 7 | |
| 8 | |
| 9 | AxisMajorTicks(all;0) /* Hide tick marks. */ |
| 10 | MajorGridLineWidths(y;x;0) /* Hide vertical grid lines. */ |
| 11 | MajorGridLineWidths(x;y;0.25) |
| 12 | |
| 13 | |
| 14 | ChartData(2 9 12 6 3) |
| 15 | |
| 16 | |
| 17 | |
| 18 | AxisOptions(all;none) /* Hide axes. */ |
| 19 | GridLocation(all;none) /* Hide grid. */ |
| 20 | |
| 21 |
OpenView() . . . CloseView() Structure
OpenDrawing(width;height[;resolution])
...
OpenView(left;top;width;height[;rotation])
...
sequence of xmCHART functions
...
...
Views make it possible to divide a drawing into rectangular regions. For example, a series of graphics primitives, such as lines, areas or texts, can be combined within a view; by simply changing the position of the view all graphic components within a view are automatically moved with it. Otherwise the coordinates of each single graphics primitive would have to changed. That means all coordinates within a view always refer to the upper left-hand corner of the view. Charts and graphics primitives, which are located partially or completely outside of a view, are clipped.
Example
| | EXAMPLE_09 |
| 1 | OpenDrawing(200;120) |
| 2 | OpenView(70;40;120;70) |
| 3 | ChartData(4 3 4 5 3) |
| 4 | |
| 5 | AreaChartOptions(on) /* After AreaChart() function. */ |
| 6 | FillStyle(1;#ffa50022) |
| 7 | BorderStyle(1;smooth;0) |
| 8 | |
| 9 | |
| 10 | AxisOptions(x;none) /* Hide x-axis. */ |
| 11 | |
| 12 | AxisMajorTicks(y;0) /* Hide y-axis tick marks. */ |
| 13 | MajorGridLineWidths(y;x;0) /* Hide vertical grid lines. */ |
| 14 | MajorGridLineWidths(x;y;0.25) |
| 15 | Background(none;;0.25;gray) |
| 16 | |
| 17 | Background(none;;0.25;gray) |
| 18 |
Nested views, i.e. views within a view, are also possible.
Example
| | EXAMPLE_10 |
| 1 | OpenDrawing(200;120) |
| 2 | OpenView(20;20;160;80) |
| 3 | AddText(3;10;"View 1";Verdana;9) |
| 4 | OpenView(20;20;50;40) |
| 5 | AddText(3;10;"View 1.1";Verdana;9) |
| 6 | Background(#be330022;solid;1;#be3300) |
| 7 | |
| 8 | OpenView(90;20;50;40) |
| 9 | AddText(3;10;"View 1.2";Verdana;9) |
| 10 | Background(#4682b422;solid;1;#4682b4) |
| 11 | |
| 12 | Background(#ffcc0022;solid;1;#ffcc00) |
| 13 | |
| 14 | Background(none;;0.25;gray) |
| 15 |
Comments
xmCHART supports two comment styles: single-line and multi-line.
A double slash (//) anywhere on a line (except within a string) turns the rest of the line into a comment. Multi-line comments begin with a slash-asterisk (/*) and end with an asterisk-slash (*/), and can span multiple lines. For example, obsolete or unfinished pieces of code can be disabled by turning them into comments. Or while testing or debugging a script, multi-line comment delimiters can be used to comment-out whole sections of code. Single-line comments inside multi-line comments are also permitted. Nested multi-line comments are supported starting with xmCHART 4.
Example
// -----------------------------------------------
// Area chart 2D
// -----------------------------------------------
OpenDrawing(600;400)
OpenChart(100;50;400;300;on) /* Plot area. */
ChartData(1 2 3 4 5; // x-values of series 1
9 5 8 8 4; // y-values of series 1
1 2 3 4 5 6; // x-values of series 2
15 9 7 0 0 1) // y-values of series 2
AreaChart2D()
//FillColorScheme(11)
BorderStyle(all;none) /* Hide borders. */
LabelStyle(all;;9;plain;60 60 60)
/* Disabled code lines:
LabelOptions(all;out)
Scaling(x;linear;0;7;7)
AxisOptions(all;none) /* Hide axes. */
MajorGridLineWidths(all;all;0) // Hide grid lines.
*/
CloseChart()
CloseDrawing()