Script Steps
The following Script Steps are used to access xmCHART 5 from FileMaker Pro and are listed in FileMaker’s Script Workspace:
| Arguments | User Name | Required. The user name is case-sensitive and has to be entered exactly as provided by X2max Software. | ||||
| Activation Code | 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–...". | |||||
| Max. Num of Users | Optional. With the 3rd argument Max. Num of Users 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:
Activate [ User Name: ... ; Activation Code: ... ; Max. Num of Users: 10 ] |
|||||
| Return Type | Text. | |||||
| Return Value | Activate[] returns "1" if the activation was successful, otherwise "0" is returned. | |||||
| Example |
Activate [ User Name: "John Q. Doe" ; Activation Code: "V5-j29-spTi77xT-dz8fnbwzt-3lbn29j" ] 
|
|||||
| 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 | External function: xmCH_Activate() | |||||
| Arguments | Source Code | 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()" |
| File Name | 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. 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 script step Get Error Message[] or Get Curve Fitting Value[] on FileMaker Server. | |
| Error Message Prefix | Optional. See script step Get Error Message[]. | |
| Return Type | Container. | |
| Return Value | PNG bitmap image. The image quality can be controlled by using the argument resolution in function OpenDrawing(). | |
| Examples |
Draw Chart [ Source Code: "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()" ]
Draw Chart [ Source Code: script ; File Name: "gantt_chart" ] |
|
| See Also | External function: xmCH_DrawChart() | |
| Arguments | Chart Index | 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. |
| Series Index | 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. | |
| Curve Fitting ID | 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. | |
| Value ID | 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 script step Get Curve Fitting Value[] 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 Draw Chart[]. The UUID must match the one you use in function Draw Chart[ ... ; ... ; 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 |
Get Curve Fitting Value [ Chart Index: 1 ; Series Index: 1 ; Curve Fitting ID: 1 ; Value ID: 1 ] /* Returns correlation coefficient r² */ Get Curve Fitting Value [ Chart Index: 1 ; Series Index: 1 ; Curve Fitting ID: 1 ; Value ID: 2 ] /* Returns coefficient c₀ */ Get Curve Fitting Value [ Chart Index: 1 ; Series Index: 1 ; Curve Fitting ID: 1 ; Value ID: 3 ] /* Returns coefficient c₁ */ Get Curve Fitting Value [ Chart Index: 1 ; Series Index: 1 ; Curve Fitting ID: -5 ; Value ID: 1 ] /* Returns the x-coordinates of the p-Spline. */ Get Curve Fitting Value [ Chart Index: 1 ; Series Index: 1 ; Curve Fitting ID: -5 ; Value ID: 2 ] /* Returns the y-coordinates of the p-Spline. */ |
|
|
The way in which the script step Get Curve Fitting Value[] works can be studied in Curve Fitting Example Databases. The files are unlocked and are available as a free download. |
||
| See Also | External function: xmCH_GetCFValue() | |
| Arguments | Message Prefix | 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 Draw Chart[]. The UUID must match the one you use in function Draw Chart[ ... ; ... ; UUID: ... ; ... ]. | |
| Return Type | Text. | |
| Return Value | Optional prefix + error message. If no error occurred, script step Get Error Message[] returns an empty string. | |
| Examples |
Get Error Message [ ] Get Error Message [ Message Prefix: "Error: " ] Get Error Message [ Message Prefix: "" ; UUID: $uuid ] |
|
| Notes | Since Draw Chart[] returns in case of an error already an error message, the script step Get Error Message[] is rarely needed. | |
| See Also | External function: xmCH_GetErrorMessage() | |
| 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 |
Get Mouse [ Format: "" ] /* Returns an empty string. */ Get Mouse [ Format: "%1" ] /* Returns, for example: "241" */ Get Mouse [ Format: "%1 %2" ] /* Returns, for example: "241 188" */ Get Mouse [ Format: "y:%2" ] /* Returns, for example: "y:188" */ Get Mouse [ Format: "(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 | External function: xmCH_GetMouse() | |
| Arguments | Format | Required. Three formats are supported: "Long" "Short" (default) "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 |
Get Version [ Format: Long ] /* Returns, for example: "xmCHART 5.0.10" */ Get Version [ Format: Short ] /* Returns, for example: "5.0.10" */ Get Version [ Format: Norm ] /* Returns, for example: "05001000" */ |
|
| See Also | External function: xmCH_GetVersion() | |
xmCHART Code Utilities
| Arguments | Source Code | Required. xmCHART script code without any references to FileMaker functions, fields or variables. |
| Theme ID | 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 |
Colorize Code [ Source Code: $code ; Theme ID: 1 ] Colorize Code [ Source Code: $code ; Theme ID: 5 ; Customize: "{comments:"lightGray"}" ] Colorize Code [ Source Code: $code ; Theme ID: 2 ; Customize: "{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 | External function: xmCH_ColorizeCode() | |
| Arguments | Source Code | Required. xmCHART script code without any references to FileMaker functions, fields or variables. |
| Format ID | 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 |
Format Code [ Source Code: $code ; Format ID: 1 ] Format Code [ Source Code: $code ; Format ID: 2 ; Customize: "{inline_comments:"remove"}" ] Format Code [ Source Code: $code ; Format ID: 3 ; Customize: "{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 | External function: xmCH_FormatCode() | |
