24U SimpleChart Plug-In 1.2 Syntax

This file describes syntax of 24U SimpleChart Plug-In's functions.

SChart_Version ( { versionFormat } )

Returns version string of the active 24U SimpleChart Plug-In, formatted as requested by the parameter.

Parameters

versionFormatDefines the format of the returned version.

Parameter values for versionFormat

shortTo get just the version number. Default value.
longTo get the plug-in name followed by its version number
platformTo get the platform of the code currently running

Description

This function is very important and it has the same output format in all 24U Plug-Ins. You should call this function every time you need to check if the plug-in is properly installed to the FileMaker. Even if the plug-in is not registered (or badly registered) this function should work. Calling this function in the startup script of your solution is recommended.

Result

Returns requested version format or platform. If this function returns "?" than the plug-in is not properly installed or FileMaker cannot load and activate it for some reason.

Examples

SChart_Version( "long" )
This will return the plug-in name and its version. In this case it is "24U SimpleChart Plug-In 1.2.1".

SChart_Version( "platform" )
Returns "Mac OS X" or "Windows" depending on the platform the plug-in is currently running.

SChart_Register ( originalSerialNumber { & " " & upgradeSerialNumber... } )

Attempts to unlock (register) your copy of 24U SimpleChart Plug-In with the specified code.

Parameters

originalSerialNumberThe original (non upgrade) code to unlock the full version of the plug-in.
upgradeSerialNumberThe upgrade code to unlock the full version of the plug-in.

Description

If the code(s) is valid, 24U SimpleChart Plug-In gets unlocked and stays in this state until you quit the FileMaker Pro application, deactivate the plug-in, or the registration code expires. While unlocked, 24U SimpleChart Plug-In is fully functional and does not bother the user with a shareware reminder.

Result

Returns a non-zero error code when the serial numbers are wrong if the numbers cannot be used. Returns 0 if the plug-in was successfully registered.

Examples

SChart_Register( "SCH12J-CM244H-U4UGBN" )
This function will register the plug-in with serial number SCH12J-CM244H-U4UGBN. This method is useful when you register the plug-in with developer license but it can be used for end-user licenses as well.

SChart_Register( "SCH10J-CM244H-U4UGBN SCH12J-BTPDSK-D3AJ9C" )
Use combination of serial numbers delimited by empty space to register using upgrade code. The first code must be the original one, all other codes should be upgrade codes.

SChart_Register( "SCH10J-CM244H-U4UGBN SCH20J-BTPDSK-D3AJ9C SCH30J-5B4J7Z-W9KFNS" )
The example of using one original number and two upgrade numbers. The original is for version 1.0 and upgrades are for 2.0 and 3.0.

Note: All serial numbers here are only for demonstration purposes. They will not work in real plug-in.

SChart_New

Creates a new chart.

Description

Use this function to create a new (empty) chart and sets parameters to default values.

Default parameters

hsizechart width - 320 pixels.
wsizechart height - 240 pixels.
backcolcolor for chart background - RGB(255,255,255) - white color.
textcolcolor for chart foreground - RGB( 0 , 0 , 0 ) - black color.
chartStyle"Pie".
chartSubStylenone.
chartNamenone.
XaxisNamenone.
YaxisNamenone.
fontName"Times" font for all texts.
fontSizescalable font for all texts.
fontColorblack color for all texts.

Result

Function returns chartdata container.

Examples

SChart_New
This will create a new chartdata container. Default setting will be used.

SChart_Data( chartdataContainer ; Xdata ; Ydata ; seriesColor { ; seriesName } )

Collect input data into the chart.

Parameters

chartdataContainerContainer, which contains chart data and picture.
XdataData for X axis.It can be strings or numbers.
YdataData for Y axis.It must be numbers.
seriesColorColor of the current series in RGB format.
seriesNameName of the current series.

Description

Collect input data (one series) into the chart. When called for the first time, it does the same thing as SChart_New before collecting data. When called for the next time, it adds current series into the chart.

Xdata and Ydata have 3 types of possible inputs.

1. fieldname or fieldname interval from current found set ( data collected using GetNthRecord function ).
2. written list of values separated by mark ( Enter or ';' ).
3. reference to field where values are stored ( in the same format as specified at point 2 ).

If Xdata contains the same values or strings, Ydata values in apropriate positions are added. It is done this way to avoid duplicity.

Result

Function returns chartdata container if there is no error in input parameters. In case of any error, error picture will be generated. See paragraph "Error pictures".

Examples

SChart_Data( SChart_New ; Test:Names ; Test::Salary ; RGB ( 255 ; 0 ; 255) ; "year 2008" )
This function will create chartdata container with a picture of a pie chart. Xdata contains all values stored in fieldname Name. Ydata contains all values stored in fieldname Salary ( 1st type ).

SChart_Data( SChart_New ; Test:Names(1-5) ; Test::Salary(1-5) ; RGB ( 255 ; 0 ; 255) ; "year 2008" )
This function will create chartdata container with a picture of a pie chart. Xdata contains values stored in fieldname Name from record 1 to record 5. Ydata contains values stored in fieldname Salary from record 1 to record 5 ( 1st type ).

SChart_Style( SChart_Data( SChart_New ; "John;Luke;Ben" ; "7;13;20" ; RGB ( 255 ; 0 ; 0) ; "year 2008") ; "VBar" )
This function will create chartdata container with a picture of a vertical bar chart. Data for this chart are directly inserted ( 2nd type ). John, Luke and Ben will be on X axis and values on Y axis will be: 10 for John, 12 for Luke and 15 for Ben. The chart will have red color and series name "year 2008".


Directly inserted data example.
 

SChart_Data( SChart_New ; Test:ListOfNames ; Test::ListOfSalary ; RGB ( 255 ; 0 ; 255) ; "year 2008" )
This function will create chartdata container with a picture of a pie chart. Xdata contains all values stored in a global fieldname Name and Ydata contains all values stored in a global fieldname Salary ( 3rd type ).

SChart_Titles( chartdataContainer ; chartName ; XaxisName ; YaxisName )

Sets basic chart titles.

Parameters

chartdataContainerContainer, which contains chart data and picture.
chartNameText for labelling the chart.
XaxisNameText for X axis of the chart.
YaxisNameText for Y axis of the chart.

Description

This function sets basic chart titles and if possible, chart will be redrawn.

Result

Function returns chartdata container if there is no error in input parameters. In case of any error, error picture will be generated.

Examples

SChart_Titles( SChart_Style( SChart_Data( SChart_New ; "John;Luke;Ben" ; "7;13;20" ; RGB ( 100 ; 0 ; 0) ; "2008" ) ; "VBar" ) ; "Best employees in year 2008" ; "Employee" ; "Salary" )
This function will add titles into vertical bar chart and modify look of the chart picture, see pictures below.


Before using SChart_Titles function.
 


After using SChart_Titles function.
 

SChart_PieColors( chartdataContainer ; color1 ; color2 ; color3 ; ... )

Modify pie color table.

Parameters

chartdataContainerContainer, which contains chart data and picture.
color1Color RGB for 1st piece of the pie chart.
color2Color RGB for 2nd piece of the pie chart.
color2Color RGB for 3rd piece of the pie chart.

Description

Pie chart has predefined color set. This function allows to set these colors by user. 256 colors can be used at most. Use this function only when current chartSyle is set to one of pie variants.

Result

Function returns chartdata container if there is no error in input parameters. In case of any error, error picture will be generated.

Examples

SChart_PieColors( SChart_Data( SChart_New ; "John;Luke;Ben" ; "7;13;20" ; RGB ( 255 ; 0 ; 0) ; "Test series") ; RGB ( 255 ; 0 ; 0 ) ; RGB ( 0 ; 255 ; 0 ) ; RGB ( 0 ; 0 ; 255 ) )
This will change first three colors of predefined color set for current pie chart , see pictures below.


Before using SChart_PieColors function.
 


After using SChart_PieColors function.
 

SChart_Style( chartdataContainer ; chartStyle { ; chartSubstyle } )

Sets chart style.

Parameters

chartdataContainerContainer, which contains chart data and picture.
chartStyleStyle of the chart. Currently there are 6 basic and 3 combined styles supported.
chartSubstyleSubstyle of the chart.

Parameter values for chartStyle

"Pie","3DPie"pie chart variants.
"Line","3DLine"line chart variants.
"Area","3DArea"area chart variants.
"HBar" or "Horizontal Bar","H3DBar" or "Horizontal 3DBar"horizontal bar chart variants.
"VBar" or "Vertical Bar","V3DBar" or "Vertical 3DBar"vertical bar chart variants.
"XYLine"true XY chart.
"ComboLineVBar, ComboLineArea, ComboLineLine"combined chart variants.

Parameter values for chartSubstyle when Style set to one of pie variants

"Percents"Pie labels will contain percent informations.(default)
"Values"Pie labels will contain value informations.
"Both"Pie labels will contain both informations.

Parameter values for chartSubstyle when Style set to one of bar variants

"Stacked"Series will be stacked in the chart.(default)
"Beside"Series will be displayed beside.

Description

Use this function to change chart style. If possible, chart will be redrawn. In these "Combo" charts , series are collected by ordinary way , but minimally 2 series must be collected.

For better understanding, let's think we collected n series using SChart_Data function. First n-1 series are the primary mentioned ChartStyle and the last series is secondary mentioned ChartStyle. For example, "ComboLineVBar" creates chart with n-1 series of Line and the last series creates VBar with Y axis on the right side.

Result

Function returns chartdata container if there is no error in input parameters. In case of any error, error picture will be generated.

Examples

SChart_Style( SChart_Data( SChart_New ; "John;Luke;Ben" ; "7;13;20" ; RGB ( 255 ; 0 ; 0) ; "series1") ; "3DPie" )
This function will modify style of the chart to 3D pie. Note that series name is not used in pie chart, because only one series make sense for any pie char.


3D pie example.
 

SChart_Style( SChart_Data( SChart_New ; "John;Luke;Ben" ; "7;13;20" ; RGB ( 255 ; 0 ; 0) ; "series1") ; "3DPie" ; "Values" )
Similar to the previous example.Using substyle "Values" will display values instead of percents around the pie.


3d pie example with values.
 

SChart_Style( SChart_Data( SChart_New ; "John;Luke;Ben" ; "7;13;20" ; RGB ( 255 ; 128 ; 0) ; "series1") ; "Area" )
This function will modify style of the chart to Area.


Area example.
 

SChart_Style( SChart_Data( SChart_New ; "John;Luke;Ben" ; "7;13;20" ; RGB ( 255 ; 128 ; 0) ; "series1") ; "VBar" )
This function will modify style of the chart to Vertical bar.


Vertical bar example.
 

SChart_Style( SChart_Data( SChart_New ; "0;8;10" ; "7;13;20" ; RGB ( 255 ; 128 ; 0) ; "series1") ; "XYLine" )
This function will modify style of the chart to true XY Line . Note that data in X axis must be entered in order from lowest to highest.


True XY line example.
 

SChart_Style( SChart_Data( SChart_Data( SChart_New ; "John;Luke;Ben" ; "7;13;20" ; RGB ( 255 ; 0 ; 0) ; "series1" ) ; "John;Luke;Ben" ; "30;34;32" ; RGB ( 255 ; 200 ; 150 ) ; "series2" ) ; "ComboLineArea" )
This function will modify style of the chart to cobmo Line and Area chart. Data from series1 are used for Line chart and data from series2 are used for Area chart.


Combo line and area example.
 

SChart_Draw( chartdataContainer ; hsize ; vsize { ; backcol ; textcol } )

Sets chart dimensions and colors and draws it.

Parameters

chartdataContainerContainer, which contains chart data and picture.
hsizeHorizontal size of the chart in pixels.
vsizeVertical size of the chart in pixels.
backcolColor RGB for the chart background.
textcolColor RGB for the chart foreground.

Description

Use this function to change chart dimensions and/or basic colors. If possible, chart will be then redrawn.

Result

Function returns chartdata container if there is no error in input parameters. In case of any error, error picture will be generated.

Examples

SChart_Draw( SChart_Style( SChart_Data( SChart_New ; "John;Luke;Ben" ; "7;13;20" ; RGB ( 255 ; 0 ; 0) ; "Test series" ) ; "HBar" ) ; 1600 ; 1200 ; RGB ( 60 ; 60 ; 60 ) ; RGB ( 255 ; 255 ; 255 ) )
This function will create horizontal bar chart with 3 bars and specified dimensions and specified background and foreground colors.

SChart_Draw( SChart_Style( SChart_Data( SChart_New ; "John;Luke;Ben" ; "7;13;20" ; RGB ( 255 ; 0 ; 0) ; "Test series" ) ; "Line" ) ; 800 ; 600 )
Similar to previous example. But a line chart is created and only dimensions will be modified. Background and foroground colors are default.

SChart_Font( chartdataContainer ; textType ; fontName ; fontSize { ; fontColor } )

Sets font and its properties for specified text.

Parameters

chartdataContainerContainer, which contains chart data and picture.
textTypeName of text for which are next parameters specified.
fontNameName of the selected font for specified textType, if specified font does not exist or empty string is inserted, default font will be used (Times) . Whole name must be inserted for example "Arial.dfont". *.ttf and *.dfont are supported.
fontSizeSize of the specified font, in case of 0 scalable font size will be used.
fontColorColor RGB for the specified textType.

Parameter values for textType

"ChartTitle"Chart main title.
"XaxisTitle"Title for X axis.
"YaxisTitle"Title for Y axis.
"YaxisTitle2"Title for 2nd Y axis when some combo style chart is used.
"XaxisTexts"Texts under X axis.
"YaxisTexts"Texts behind Y axis.
"PieLabels""Texts around pie style chart.

Description

Use this function to set font and its properties for specified text. If possible, chart will be redrawn.

Result

Function returns chartdata container if there is no error in input parameters. In case of any error, error picture will be generated.

Examples

SChart_Font( SChart_Titles( SChart_Style ( SChart_Data( SChart_New ; "John;Luke;Ben" ; "7;13;20" ; RGB ( 100 ; 0 ; 0) ; "2008" ) ; "VBar" ) ; "Best employees in year 2008" ; "Employee" ; "Salary" ) ; "ChartTitle" ; "Arial.dfont" ; 16 ; RGB ( 255 ; 0 ; 0) )
This function will change current ChartTitle font to Arial, size 16 pixels, red color in PictureContainer and modify look of the chart picture, see picture below.


Before using SChart_Font function.
 


After using SChart_Font function.
 

Error pictures

Here you can see all error pictures SimpleChart Plug-In can generate, every one with description.


Error in some SChart_Data parameter.
 


1000 or more values inserted to SChart_Data, unable to draw chart.
 


Error in SChart_Data parameter Xdata.
 


Error in SChart_Data parameter Ydata.
 


Error in some SChart_Titles parameter.
 


Error in some SChart_Font parameter.
 


Error in some SChart_Style parameter.
 


Error in some SChart_Draw parameter.
 


Error in some SChart_Color parameter.
 


Plug-In expired, unable to draw chart.
 


Plug-In licences exceeded, unable to draw chart.