External Functions
External functions are used to access xmCHART from FileMaker Pro and are listed in FileMaker’s Specify Calculation dialog box. By convention, the names of xmCHART’s external functions are prefixed by "xmCH_".
The following external functions are available in xmCHART 5:
| Arguments | userName | Required. The user name is case-sensitive and has to be entered exactly as provided by X2max Software. | ||||
| activationCode | Required. The activation code is case-sensitive and has to be entered exactly as provided by X2max Software. All activation codes for xmCHART 5 are prefixed by "V5–...", all activation codes for xmCHART 4 are prefixed by "V4–...". | |||||
| maxNumOfUsers | Optional. With the 3rd argument maxNumOfUsers it is possible for developers to control the display of the maximum number of users per company in the xmCHART plug-in window (under FileMaker Pro menu item: Preferences... > Plug-Ins). This can be advantageous should you wish to individually design licenses for your database solutions. Assuming you hold a xmCHART Developer License for a maximum of 25 users/company: one time you license one of your database solutions for a max. of 25 users per company, another time, for example, for a max. of 10 users. In the latter case you can adapt the display in the xmCHART plug-in window accordingly by entering:
xmCH_Activate(yourUserName;yourActivationCode;10) |
|||||
| Return Type | Text. | |||||
| Return Value | xmCH_Activate() returns "1" if the activation was successful, otherwise "0" is returned. It is important to assign xmCH_Activate() to a FileMaker Pro field or variable, otherwise xmCHART is not activated. Please note, up to version xmCHART 4.0.10 the external function xmCH_Activate() returns always an empty string, regardless of whether the activation was successful or not. |
|||||
| Examples |
xmCH_Activate("John Q. Doe";"V5-j29-spTi77xT-dz8fnbwzt-3lbn29j") xmCH_Activate("Jane Doe Software";"V5-43sQ-kabt6-Wid9r1cc4A-jmRw98KvV3Css";10) 
|
|||||
| Notes |
Important: Since neither the user name nor the activation code is saved in a Preferences file or Registry entry, one of the following options for activating xmCHART is recommended:
|
|||||
| See Also | Script Step: Activate[] | |||||
| Arguments | sourceCode | Required. Contains a list of xmCHART functions arranged as a large string of text in the form:
"OpenDrawing(width;height[;resolution]) ... list of xmCHART functions ... CloseDrawing()" |
| fileName | Optional. The entered filename is shown in FileMaker’s Export Field to File dialog box under FileMaker Pro menu item: Edit > Export Field Contents...
|
|
| uuid | Optional. An uuid works like a session ID and makes it possible to access internal charting values such as curve fitting coefficients in a FileMaker server environment. You can safely ignore the uuid or simply enter an empty string unless you want to use the external functions xmCH_GetErrorMessage() or xmCH_GetCFValue() on FileMaker Server. | |
| errorMessagePrefix | Optional. See external function xmCH_GetErrorMessage(). | |
| Return Type | Container. | |
| Return Value | PNG bitmap image. The image quality can be controlled by using the argument resolution in function OpenDrawing(). | |
| Examples |
xmCH_DrawChart("OpenDrawing(400;300) ChartData(2 4 5; 3 1 1; 5 4 2 2; 1 4 2 5; 7 6 1 4) BarChart(shadow+label) FillColorScheme(desert;shaded) BorderStyle(all;none) CloseDrawing()")
xmCH_DrawChart(sourceCode;"gantt_chart";"";"003$$") xmCH_DrawChart(sourceCode;"MyDrawing";$uuid) xmCH_DrawChart(sourceCode;"MyDrawing";"";"103") |
|
| See Also | Script Step: Draw Chart[] | |
| Arguments | chartIndex | Required. Since several charts can be drawn at the same time within a drawing, it is necessary to specify the chart by using an index. The index corresponds to the order of chart definitions within OpenDrawing() and CloseDrawing(). If the drawing only consists of one chart, chartIndex is 1. |
| seriesIndex | Required. The series index is used to determine which series the inquiry refers to. This is necessary as curve fittings for several series can be carried out simultaneously. | |
| curveFittingID | Required. The curve function index is used to define which curve function should be accessed. This is necessary as several curve fittings can be calculated simultaneously for one data series. The curve function index is identical to the argument type and has a value between -5 and 6. See Curve Fitting Constants. | |
| valueID | Required. The value index makes it possible to access individual coefficients. Value index 1 returns the correlation coefficient r², value index 2 the curve coefficient c₀, value index 3 the curve coefficient c₁, etc. | |
| format | Optional. As an option, the coefficient returned by the function xmCH_GetCFValue() can be formatted accordingly by using a format specifier. If no format specifier is defined, the default format specifier "|u|" is used. All format specifiers including numerous examples can be found in Output Numbers. | |
| uuid | Optional. An uuid is only required if xmCHART is installed on FileMaker Server. The uuid enables you to access the calculated curve fitting coefficients after calling xmCH_DrawChart(). The uuid must match the one you use in function xmCH_DrawChart(...;...;uuid;...) | |
| Return Type | Text. | |
| Return Value | Returns for curve fitting type -5 (pSpline) the coordinates of the p-spline and for curve fitting types between -4 and 6 a single curve fitting coefficient. | |
| Examples |
xmCH_GetCFValue(1;1;1;1) /* Returns correlation coefficient r² */ xmCH_GetCFValue(1;1;1;2) /* Returns coefficient c₀ */ xmCH_GetCFValue(1;1;1;3) /* Returns coefficient c₁ */ xmCH_GetCFValue(1;1;-5;1) /* Returns the x-coordinates of the P-spline. */ xmCH_GetCFValue(1;1;-5;2) /* Returns the y-coordinates of the P-spline. */ xmCH_GetCFValue(1;1;1;3;"|f6|";$uuid) |
|
|
The way in which the function xmCH_GetCFValue() works can be studied in Curve Fitting Example Databases. The files are unlocked and are available as a free download. |
||
| See Also | Script Step: Get Cuxxxxxxxrve Fitting Value[] | |
| Arguments | messagePrefix | Optional. For example: "Error: ", default is: "" (empty). |
| uuid | Optional. An uuid is only required if xmCHART is installed on FileMaker Server. The uuid enables you to access information about the last error that occurred while trying to execute xmCH_DrawChart(). The uuid must match the one you use in function xmCH_DrawChart(...;...;uuid;...). | |
| Return Type | Text. | |
| Return Value | Optional prefix + error message. If no error occurred, the function xmCH_GetErrorMessage() returns an empty string. | |
| Examples |
xmCH_GetErrorMessage xmCH_GetErrorMessage("Error: ") xmCH_GetErrorMessage("";$uuid) |
|
| Notes | Since xmCH_DrawChart() returns in case of an error already an error message, the external function xmCH_GetErrorMessage() is rarely needed. | |
| See Also | Script Step: Get Error Message[] | |
| Arguments | format | Required. format can be any text string with %1 and %2 as placeholders for the x and y coordinates. |
| Return Type | Text. | |
| Return Value | Current mouse coordinates measured in pixels with the origin in the top-left corner of the FileMaker layout area. The returned coordinates do not include any horizontal or vertical scroll offsets. | |
| Examples |
xmCH_GetMouse("") /* Returns an empty string. */ xmCH_GetMouse("%1") /* Returns, for example: "241" */ xmCH_GetMouse("%1 %2") /* Returns, for example: "241 188" */ xmCH_GetMouse("y:%2") /* Returns, for example: "y:188" */ xmCH_GetMouse("(x=%1 y=%2)") /* Returns, for example: "(x=241 y=188)" */ |
|
| Notes |
xmCH_GetMouse() is not supported on FileMaker Server, FileMaker Go and in FileMaker WebDirect.
Important: To get the correct mouse position: 
|
|
| See Also | Script Step: Get Mouse[] | |
| Arguments | format | Required. Three formats are supported: 1 or "Long" 2 or "Short" (default) 3 or "Norm" |
| Return Type | Text. | |
| Return Value | xmCHART version info. Format "Norm" returns the normalized xmCHART version info as an 8-character string in the format: Major version (2 characters) Minor version (2 characters) Patch version (2 characters) Build number (2 characters) |
|
| Examples |
xmCH_GetVersion("") /* Returns, for example: "5.0.10" */ xmCH_GetVersion("Long") /* Returns, for example: "xmCHART 5.0.10" */ xmCH_GetVersion("Short") /* Returns, for example: "5.0.10" */ xmCH_GetVersion("Norm") /* Returns, for example: "05001000" */ |
|
| See Also | Script Step: Get Version[] | |
| Arguments | languageID | Required. Currently, the languages English and German are supported. Language ID for English: 0 or "en" Language ID for German: 1 or "de" |
| Return Type | Text. | |
| Return Value | Language ID ("0" for English, "1" for German). | |
| Examples |
xmCH_SetLanguage("") /* English (default) */ xmCH_SetLanguage("en") /* English */ xmCH_SetLanguage("de") /* German */ xmCH_SetLanguage( 0 ) /* English */ xmCH_SetLanguage( 1 ) /* German */ |
|
| Notes | Deprecated. The language setting affects error messages and the legend default texts: "Series 1", "Series 2", ... | |
xmCHART Code Utilities
| Arguments | sourceCode | Required. xmCHART script code without any references to FileMaker functions, fields or variables. |
| themeID | Required. Five predefined color themes [1..5] are available. Color theme 0 means no coloring. | |
| customize | Optional. Color themes can be customized by adding an optional JSON object. Fives style categories are supported: { function_names : ["<color>","<fontface>"] strings : ["<color>","<fontface>"] numbers : ["<color>","<fontface>"] constants : ["<color>","<fontface>"] comments : ["<color>","<fontface>"] } Short form: Instead of a single element array, you may specify a simple key/value pair. See examples below. |
|
| Return Type | Text. | |
| Return Value | Colorized source code. | |
| Examples |
xmCH_ColorizeCode(sourceCode;1) xmCH_ColorizeCode(sourceCode;5;"{comments:"lightGray"}") xmCH_ColorizeCode($code;2;"{comments:["lightGray","italic"],strings:"#f00",function_names:["200 100 0","boldItalic"]}") Syntax coloring is demonstrated in database xmCHART_Colorizer.fmp12 — part of the xmCHART 5 download. |
|
| See Also | Script Step: Colorize Code[] | |
| Arguments | sourceCode | Required. xmCHART script code without any references to FileMaker functions, fields or variables. |
| formatID | Required. Four formatting styles [1..4] are supported. Format ID 0 means no formatting. 0...Untouched: No formatting. 1...Compressed: Remove all comments, line breaks and extra whitespace. 2...Tight: Indent code blocks and remove whitespace and line breaks around function parentheses and argument separators. 3...Loose: Indent code blocks and add a single space around function parentheses and argument separators. 4...IndentOnly: Indent comments and code blocks, but leave the code untouched. |
|
| customize | Optional. Formatting can be customized by adding an optional JSON object. The following options are available: indent_spaces: default: 2 max_empty_lines: default: -1 /* -1...untouched. */ function_name_notation: options: "uppercase","lowercase","camelcase" /* Ignored in combination with indentOnly style. */ constant_name_notation: options: "uppercase","lowercase","camelcase" /* Ignored in combination with indentOnly style. */ inline_comments: options: "remove" /* Only applicable for tight and loose formatting styles. */ |
|
| Return Type | Text. | |
| Return Value | Formatted source code. Please note, all syntax color information is lost while formatting. | |
| Examples |
xmCH_FormatCode(sourceCode;1) xmCH_FormatCode(sourceCode;5;"{inline_comments:"remove"}") xmCH_FormatCode($code;1;"{indent_spaces:2,max_empty_lines:1,function_name_notation:"uppercase"}") Code formatting is demonstrated in database xmCHART_Formatter.fmp12 — part of the xmCHART 5 download. |
|
| See Also | Script Step: Format Code[] | |
