Chart Director API for APPX

This API can be used by an APPX designer to create business charts within an APPX application.

Known Issues

The Linear Meter chart type has a few problems:
- The pointer files (PTR1/2) are not initialized when .CHART INITIALIZE is called, so each time you call .CHART RENDER, the previously defined pointers appear as well as the one(s) you intended for the current chart.
- The PRT1/2 files are not linked to a particular CHTSPEC record, so if you are working with multiple charts of this type, when you render a chart the pointer(s) will appear on all charts, not just the current one.
The .CHART SET BG IMAGE routine does not pick up images in the default image directory, only a full pathname works
- It verifies the file exists only for a full pathname, should verify image directory as well
- Also check .CHART SET BG WALLPAPR, probably has the same problem.
The examples in 1CD have the path /var/www/html/ChartDirector/phpdemo hardcoded. This path can vary depending on Windows vs Linux installation. The examples should probably check the server type and use the appropriate default.
The .CHART SET EXT CLR routine is mentioned here but does not exist.
The .CHART SET SHAPE AA seems to update the memory file, but unless you also call .CHART SET TXT AA MODE, nothing gets put in the php script. Even if you call .CHART SET TXT AA MODE, the parameter for shape AA is always true, even if you turned it off via .CHART SET SHAPE AA
The .LEGEND SET ICON GAP seems to update the memory file, but unless you also call .LEGEND SET ICON SZ, nothing gets written to the php script.
The .LEGEND SET TEMPLATE causes the chart to fail to render unless you enclose the text in "'s. When generating the php script, the API should do this automatically.
Setting the vertical gap via .LEGEND SET GAP:V doesn't work unless you also set the horizontal gap via .LEGEND SET GAP:H. If the horizontal gap is not set, the php script doesn't include the setKeySpacing method, which controls both horizontal & vertical.

Overview

Release 5.1.0 of the APPX Utility includes a new designer API which can be used to create charts within an APPX application. This API provides APPX Designers with a robust set of subroutines which can be called to design charts, define datasets, and render charts using datasets. These charts can then be dynamically embedded in APPX menus, input screens, and PDF reports.

Using the API

There are some key concepts you should understand before using the Chart Design subroutines.

Designing a Chart

Chart design is accomplished by calling the appropriate Chart Design subroutines in the appropriate sequence to create a chart specification.

Defining a Dataset

Datasets are defined by calling the appropriate Dataset Design subroutines in the appropriate sequence to create a dataset definition.

Rendering a Chart

A chart is rendered by calling the Chart Render subroutine for a chart specification and its associated dataset definition(s).

Base Chart Routines

Base Chart Routines - General

.CHART INITIALIZE

Initialize a chart.

.CHART RENDER

Render the "current" chart.

.CHART SET CURRENT

Set the "current" chart to be a previously initialized chart.

.CHART GET NAME

Get the name of the "current" chart.

.CHART SET TITLE

Set the title of the "current" chart.

.CHART SET LEGEND BOX

Set a Legend Box at the specified X and Y coordinates of the "current" chart.

Base Chart Routines - Background

.CHART SET BG SIZE

Set the size (height and width) of the "current" chart.

.CHART SET BG SIZE:H

Set the height of the "current" chart.

.CHART SET BG SIZE:W

Set the width of the "current" chart.

.CHART SET BG COLOR

Set the background color of the "current" chart to the "current" color.

.CHART SET BG WALLPAPR

Set the pathname of a wallpaper image that is to be tiled within the background area of the "current" chart.

.CHART SET BG IMAGE

Set the pathname of an image file that is to be positioned within the background area of the "current" chart.

Base Chart Routines - Edge Options

.CHART SET EDGE COLOR

Set the edge color of the "current" chart.

.CHART SET EDGE EFFECT

Set the edge effect of the "current" chart.

.CHART SET EDGE WIDTH

Set the edge width of the "current" chart. Used in conjunction with Edge Effect.

Base Chart Routines - Corner Options

.CHART SET CNR STYLE

Set the corner style (Square or Rounded) of the "current" chart.

.CHART SET CNR R

Set the corner radius' of the "current" chart.

.CHART SET CNR R:TL

Set the radius of the Top Left corner of the "current" chart.

.CHART SET CNR R:TR

Set the radius of the Top Right corner of the "current" chart.

.CHART SET CNR R:BR

Set the radius of the Bottom Right corner of the "current" chart.

.CHART SET CNR R:BL

Set the radius of the Bottom Left corner of the "current" chart.

.CHART SET EXT CLR

Set the exterior color for rounded corners and/or the Drop Shadow effect of the "current" chart.

Base Chart Routines - Drop Shadow Options

.CHART SET DROP SHADOW

Set the Drop Shadow Effect to be On or Off for the "current" chart.

.CHART SET DS COLOR

Set the Color of the Drop Shadow Effect for the "current" chart.

.CHART SET DS LOC

Set the X and Y coordinates of the offset of the Drop Shadow Effect for the "current" chart.

.CHART SET DS LOC:X

Set the X coordinate of the offset of the Drop Shadow Effect for the "current" chart.

.CHART SET DS LOC:Y

Set the Y coordinate of the offset of the Drop Shadow Effect for the "current" chart.

.CHART SET DS BLUR RAD

Set the Blur Radius of the Drop Shadow Effect for the "current" chart.

.CHART SET EXT CLR

Set the exterior color for rounded corners and/or the Drop Shadow effect of the "current" chart.

Base Chart Routines - Options

.CHART SET TRANS TYPE

Set the Transparency Type for the "current" chart.

.CHART SET TRANS COLOR

Set the Transparency Color for the "Current" chart. This field is usually set in conjunction with the "Single Color" Transparency Type.

.CHART SET SHAPE AA

Set the Shape Anti-Alias to be On or Off for the "current" chart.

.CHART SET TXT AA MODE

Set the Text Anti-Alias Mode for the "current" chart.

Not Yet Implemented

.CHART ADD TO MULTI

Add the "current" chart object to the specified Multi-Chart.

.CHART ADD EM CHART

Add the specified chart object to the "current" Multi-Chart.

Base Chart Routines - Legend Box

.LEGEND SET TEMPLATE

Set the template of the legend text for the "current" Legend Box.

.LEGEND SET KEY LAYOUT

Set the Layout Method for the Legend Keys for the "current" Legend Box.

.LEGEND SET KEY COLS

Set the number of columns to be used with the "Columnar" Key Layout Method for the "current" Legend Box.

.LEGEND SET KEY ORDER

Set the key order to be ascending or descending for the "current" Legend Box.

.LEGEND SET ICON SZ

Set the width and height of the legend key icons for the "current" Legend Box.

.LEGEND SET ICON SZ:W

Set the width of the legend key icons for the "current" Legend Box.

.LEGEND SET ICON SZ:H

Set the height of the legend key icons for the "current" Legend Box.

.LEGEND SET ICON GAP

Set the distance between the Legend icon and the Legend text.

.LEGEND SET KEY GAP

Set the horizontal gap between two legend entries for horizontal legend layout and the vertical gap (line spacing) between the legend keys for the "current" Legend Box.

.LEGEND SET KEY GAP:H

Set the horizontal gap between two legend entries for horizontal legend layout for the "current" Legend Box.

.LEGEND SET KEY GAP:V

Set the vertical gap (line spacing) between the legend keys of the "current" Legend Box.

.LEGEND SET ICON E CLR

Set the edge color for the key icons for the "current" Legend Box. Applies only to rectangular icons.

.LEGEND SET ICON E EFF

Set the edge effect for the key icons for the "current" Legend Box. Applies only to rectangular icons.

.LEGEND SET ICON E W

Set the edge width for the key icons for the "current" Legend Box. Used in conjunction with Edge Effect.

.LEGEND SET KEY STYLE

Set the key style for the "current" Legend Box.

Base Chart Routines - Legend Box Keys

.LEGEND KEY ADD NEXT

Add the next legend box key to the "current" Legend Box.

.LEGEND KEY INITIALIZE

Initialize a legend box key at the specified position for the "current" Legend Box.

.LEGEND KEY SET LN W

Set the line width for a legend key that represents lines in line charts at the specified legend key position for the "current" Legend Box.

Pie Chart Routines

Pie Chart Routines - General

.PIE SET DATASET

Associate a dataset with the pie chart.

.PIE SET ORIGIN

Set the x and y coordinates (horizonal and vertical) of the center of the pie.

.PIE SET ORIGIN:X

Set the x coordinate (horizontal) of the center of the pie.

.PIE SET ORIGIN:Y

Set the y coordinate (vertical) of the center of the pie.

.PIE SET RADIUS

Set the radius of the pie.

Pie Chart Routines - 3D View

.PIE SET VIEW

Set the view of the pie to be 2D or 3D.

.PIE SET 3D MODE

Set the 3D mode to be Standard or Shadow.

.PIE SET 3D DEPTH

Set the 3D depth of the pie.

.PIE SET 3D VIEW ANGLE

Set the 3D viewing angle of the pie.

Pie Chart Routines - Donut Style

.PIE SET SHAPE

Set the shape of the pie to be Standard or Donut.

.PIE SET RADIUS:OUTER

Set the outer radius of a Donut pie.

.PIE SET RADIUS:INNER

Set the inner radius of a Donut pie.

Pie Chart Routines - Sector Layout

.PIE SET LAYOUT

Set the starting angle of the first sector in the pie and the layout direction for the pie sectors.

.PIE SET LAYOUT:ANGLE

Set the starting angle of the first sector in the pie.

.PIE SET LAYOUT:DIR

Set the layout direction for the pie sectors.

Pie Chart Routines - Label Options

.PIE SET LBL BOUNDS

Set the Top and Bottom bounds for the pie sector labels (Side Label Layout only).

.PIE SET LBL BOUNDS:T

Set the Top bound for the pie sector labels (Side Label Layout only).

.PIE SET LBL BOUNDS:B

Set the Bottom bound for the pie sector labels (Side Label Layout only).

Pie Chart Sector Routines

The following routines can be used to create or initialize pie sector specs and set the various sector style attributes.

Pie Chart Sector Routines - General

.PIE SECT INITIALIZE

Initialize a specific pie sector spec.

.PIE SECT ADD NEXT

Add a next pie chart sector spec for the "current" pie chart and optionally sets the corresponding data value and the corresponding Label.

.PIE SECT SET CURRENT

Set the "current" pie chart sector to be a previously initialized pie sector of the "current" chart.

Pie Chart Sector Routines - Background Options

.PIE SET SECT BG CLR

Set the background color for all pie sectors, a range of pie sectors, an individual pie sector, or the current pie sector.

.PIE SET SECT SHADING

Set the Shading Method for all pie sectors, a range of pie sectors, an individual pie sector, or the current pie sector.

Pie Chart Sector Routines - Edge Options

.PIE SET SECT EDGE CLR

Set the Edge Color for all pie sectors, a range of pie sectors, an individual pie sector, or the current pie sector.

.PIE SET SECT EDGE W

Set the Edge Width for all pie sectors, a range of pie sectors, an individual pie sector, or the current pie sector.

Pie Chart Sector Routines - Explode Options

.PIE SET SECT POSITION

Set the Position (Normal or Exploded) for all pie sectors, a range of pie sectors, an individual pie sector, or the current pie sector.

.PIE SET SECT EXP DIST

Set the Explosion Distance for all pie sectors, a range of pie sectors, an individual pie sector, or the current pie sector.

Pie Chart Sector Routines - Labels

The following routines can be used to set the various label attributes for all pie sectors, a range of pie sectors, an individual pie sector, or the "current" pie sector.

.PIE SET SECT LABEL

Set the Label text of an individual pie sector or the "current" pie sector.

.PIE SET LBL LAYOUT

Set the Label Layout Method (Inside, Circular, Side) for all pie sectors, a range of pie sectors, an individual pie sector, or the "current" pie sector.

.PIE SET LBL DISTANCE

Set the Distance between the pie perimeter and the pie sector labels for all pie sectors, a range of pie sectors, an individual pie sector, or the "current" pie sector. The Label Distance is usually specified in conjunction with a Label Layout Method. If a Label Distance is specified and a Label Layout Method is not specified, the Circular method is used.

.PIE SET LBL JN LN CLR

Set the Color of the lines that join the pie sector perimeter with the pie sector labels for all pie sectors, a range of pie sectors, an individual pie sector, or the "current" pie sector.

.PIE SET LBL JN LN W

Set the Width of the lines that join the pie sector perimeter with the pie sector labels for all pie sectors, a range of pie sectors, an individual pie sector, or the "current" pie sector.

.PIE SET LBL FORMAT

Set the Format for the pie sector labels for all pie sectors, a range of pie sectors, an individual pie sector, or the "current" pie sector.

Not Yet Implemented

The following routines have not been implemented. However, until such time as they are implemented, the corresponding .TEXT routines can be used instead.

.PIE SET LBL FONT NAM

Set the font name and font index for all sectors of the current pie chart.

.PIE SET LBL FONT IDX

Set the font index for all sectors of the current pie chart.

.PIE SET LBL FONT STL

Set the font style (normal, bold, italic) for all sectors of the current pie chart.

.PIE SET LBL FONT SZ

Set the font size for all sectors of the current pie chart.

.PIE SET LBL FONT CLR

Set the font color for all sectors of the current pie chart.

.PIE SET LBL ROTATION

Set the rotation angle for all sectors of the current pie chart.

XY Chart Routines

General

.XY SET PLOT AREA

Set the position and size of the plot area.

.XY SET PLOT AREA:X

Set the x coordinate of the plot area position.

.XY SET PLOT AREA:Y

Set the y coordinate of the plot area position.

.XY SET PLOT AREA:W

Set the width of the plot area.

.XY SET PLOT AREA:H

Set the height of the plot area.

.XY SET PA BG CLR

Set the Plot Area background colors.

.XY SET PA EDGE CLR

Set the Plot Area edge color.

.XY SET PA HGRID CLR

Set the Plot Area horizontal grid color.

.XY SET PA VGRID CLR

Set the Plot Area vertical grid color.

.XY ADD BAR LAYER

Adds a Bar layer to the current chart spec.

.XY SET BAR CLR

Set the color of the bars in the current Data Point, Data Set, Data Group, or XY Bar Layer

.XY SET BAR CLR:DP

Set the color of the bars for the current Data Point

.XY SET BAR CLR:DS

Set the color of the bars for the current Data Set

.XY SET BAR CLR:DG

Set the color of the bars for the current Data Group

.XY SET BAR CLR:LR

Set the color of the bars for the current XY Bar Layer

.XY SET BAR GAP

Set the horizontal gap between the bars.

.XY SET BAR GAP:BTW

.XY SET BAR GAP:WITHIN

.XY SET BAR LBL MIN SZ

.XY SET BAR LEGEND ISZ

.XY SET BAR LEGEND TXT

.XY SET BAR OLAP

.XY SET BAR OLAP:ORDER

.XY SET BAR OLAP:RATIO

.XY SET BAR SHAPE

Set the shape of the bars in the current Data Point, Data Set, Data Group, or XY Bar Layer

.XY SET BAR SHAPE:DP

Set the shape of the bars for the current Data Point

.XY SET BAR SHAPE:DS

Set the shape of the bars for the current Data Set

.XY SET BAR SHAPE:DG

Set the shape of the bars for the current Data Group

.XY SET BAR SHAPE:LR

Set the shape of the bars for the current XY Bar Layer

.XY SET BAR W

.XY SET BAR W:GROUP

.XY SET BAR W:WITHIN

.XY SET BAR 3D DEPTH

Set the 3D depth of the current bar layer.

Axis Routines

General

.AXIS SET CURRENT

Set the specified axis ("x", "y") of the "current" chart to be the "current" axis. (a second optional parameter can specify "Primary" or "Secondary")

.AXIS SET AXIS CLR

Set the color of the "current" axis.

.AXIS SET AXIS L

Set the length of the "current" axis line.

.AXIS SET AXIS W

Set the width of the "current" axis line.

.AXIS SET AXIS MARGIN

Set the margins (top and bottom/left and right) of the "current" axis.

.AXIS SET AXIS MODE

Set the axis mode of the "current" axis to be INDENTED or DEFAULT.

.AXIS SET AXIS OFFSET

Set the offset (x and y) of the "current" axis.

.AXIS SET AXIS SCALE

Set the top extension, bottom extension, and zero affinity values that are to be used when auto-scaling the "current" axis.

.AXIS SET AXIS RND MIN

Set to "true" if the minimum value of the "current" axis should be rounded to correspond with a tick value. (true, false, or blank allowed)

.AXIS SET AXIS RND MAX

Set to "true" if the maximum value of the "current" axis should be rounded to correspond with a tick value. (true, false, or blank allowed)

.AXIS SET AXIS VAL DIR

Set the direction for the values of the "current" axis. (NORMAL or REVERSE)

Axis Tick Routines

.AXIS SET TICK CLR

Set the color of the (major and minor) ticks on the "current" axis.

.AXIS SET TICK L

Set the length of the (major and minor) ticks on the "current" axis.

.AXIS SET TICK W

Set the width of the (major and minor) ticks on the "current" axis.

.AXIS SET TICK OFFSET

Set the offset of the ticks on the "current" axis.

.AXIS SET TICK MIN INC

Set the minimum tick increment of the ticks on the "current" axis.

.AXIS SET TICK DENSITY

Set the distance in pixels between major ticks and minor ticks on the "current" axis.

Axis Title Routines

.AXIS SET TITLE

Set a title for the "current" axis. (creates a TEXTSPEC record which then becomes the current TEXT spec similar to .CHART SET TITLE)

.AXIS SET TTL FONT NAM

Set the font name and font index for the title of the "current" Axis. (set the current textspec to be the axis title TEXTSPEC of the current axis and call .TEXT SET FONT NAME)

.AXIS SET TTL FONT IDX

Set the font index for the title of the "current" axis. (set the current textspec to be the axis title TEXTSPEC of the current axis and call .TEXT SET FONT INDEX)

.AXIS SET TTL FONT STL

Set the font style (normal, bold, italic) for the title of the "current" axis. (set the current textspec to be the axis title TEXTSPEC of the current axis and call .TEXT SET FONT STYLE)

.AXIS SET TTL FONT SZ

Set the font size for the title of the "current" axis. (set the current textspec to be the axis title TEXTSPEC of the current axis and call .TEXT SET FONT SZ)

.AXIS SET TTL FONT CLR

Set the font color for the title of the "current" axis. (set the current textspec to be the axis title TEXTSPEC of the current axis and call .TEXT SET FONT CLR)

.AXIS SET TTL ALIGN

Set the alignment of the axis title relative to the axis for the "current" axis.

.AXIS SET TTL GAP

Set the gap between the axis title and the axis for the "current" axis. Note: Title gap does not seem to work correctly in all cases. Possible bug in Chart Director.

Axis Label Routines

.AXIS LABEL ADD NEXT

Add the next label to the "current" Axis of the "current" chart.

.AXIS SET LBL FONT NAM

Set the font name and font index for the "current" label of the "current" Axis. (set the current textspec to be the current label TEXTSPEC of the current axis and call .TEXT SET FONT NAME)

.AXIS SET LBL FONT IDX

Set the font index for the "current" label of the "current" axis. (set the current textspec to be the current label TEXTSPEC of the current axis and call .TEXT SET FONT INDEX)

.AXIS SET LBL FONT STL

Set the font style (normal, bold, italic) for the "current" label of the "current" axis. (set the current textspec to be the current label TEXTSPEC of the current axis and call .TEXT SET FONT STYLE)

.AXIS SET LBL FONT SZ

Set the font size for the "current" label of the "current" axis. (set the current textspec to be the current label TEXTSPEC of the current axis and call .TEXT SET FONT SZ)

.AXIS SET LBL FONT CLR

Set the font color for the "current" label of the "current" axis. (set the current textspec to be the current label TEXTSPEC of the current axis and call .TEXT SET FONT CLR)

.AXIS SET LBL ROTATION

Set the rotation angle for the "current" label of the "current" axis. (set the current textspec to be the current label TEXTSPEC of the current axis and call .TEXT SET LBL ROTATION)

.AXIS SET LBL FORMAT

Set the Format for the axis labels for the "current" axis. (The label format field is stored in the LABEL1 spec record.).

.AXIS SET LBL GAP

Set the distance between the axis label and the tick in pixels for the "current" axis.

.AXIS SET LBL OFFSET

Set the offset of the labels and the offset units for the the "current" axis. The offset units is an optional second parameter. The default for the offset unit is pixels.

Data Routines

Dataset Routines

.DATASET INITIALIZE

Initialize a Dataset.

.DATASET SET CURRENT

Set the "current" Dataset to be a previously initialized Dataset.

.DATASET GET NAME

Get the name of the "current" Dataset.

Dataset Point Routines

.POINT ADD NEW

Add a new Point to the "current" Dataset. Also create a corresponding sector spec for the "current" (pie) chart if one does not exist.

.POINT SET VALUE

Set the value of the "current" Point in the "current" Dataset.

Text Box Routines

General Text Box Routines

.TEXT INITIALIZE

Initialize a Text Object

.TEXT SET CURRENT

Set the "current" Text Object to be a previously initialized Text Object.

.TEXT GET NAME

Get the name of the "current" Text Object.

.TEXT SET TEXT

Set the text of the "current" Text Object.

Font Routines

.TEXT SET FONT NAME

Set the font name and font index for the "current" Text Object.

.TEXT SET FONT INDEX

Set the font index.

.TEXT SET FONT STYLE

Set the font style (normal, bold, italic) for the "current" Text Object.

.TEXT SET FONT SZ

Set the font size for the "current" Text Object.

.TEXT SET FONT SZ:H

Set the height of the font for the "current" Text Object.

.TEXT SET FONT SZ:W

Set the width of the font for the "current" Text Object.

.TEXT SET FONT CLR

Set the font color for the "current" Text Object.

Text Box Routines

.TEXT SET BX BG CLR

Set the background color for the "current" Text Object.

.TEXT SET BX EDGE CLR

Set the edge color for the "current" Text Object.

.TEXT SET BX EDGE EFF

Set the edge effect (Flat, Raised, or Depressed) of the "current" Text Object.

.TEXT SET BX EDGE W

Set the edge width of the "current" Text Object.

.TEXT SET BX CNR STYLE

Set the corner style (Square or Rounded) of the "current" Text Object.

.TEXT SET BX CNR R

Set the corner radius of the "current" Text Object.

.TEXT SET BX CNR R:TL

Set the radius of the Top Left corner of the "current" Text Object.

.TEXT SET BX CNR R:TR

Set the radius of the Top Right corner of the "current" Text Object.

.TEXT SET BX CNR R:BR

Set the radius of the Bottom Right corner of the "current" Text Object.

.TEXT SET BX CNR R:BL

Set the radius of the Bottom Left corner of the "current" Text Object.

.TEXT SET BX LOC

Set the location (x and y) of the "current" Text Object.

.TEXT SET BX LOC:X

Set the x coordinate of the location of the "current" Text Object.

.TEXT SET BX LOC:Y

Set the y coordinate of the location of the "current" Text Object.

.TEXT SET BX SZ

Set the size (height and width) of the "current" Text Object.

.TEXT SET BX SZ:H

Set the height of the "current" Text Object.

.TEXT SET BX SZ:W

Set the width of the "current" Text Object.

.TEXT SET BX Z ORDER

Set the Z Order of the "current" Text Object.

Text Format Routines

.TEXT SET TXT MAX SZ

Set the maximum size (width and height) of the text that can be displayed in the "current" Text Object.

.TEXT SET TXT MAX SZ:W

Set the maximum width (in pixels) of the text that can be displayed in the "current" Text Object.

.TEXT SET TXT MAX SZ:H

Set the maximum height (in lines) of the text that can be displayed in the "current" Text Object.

.TEXT SET TXT MARGIN

Set the margins for the text in the "current" Text Object.

.TEXT SET TXT MARGIN:L

Set the Left margin for the text in the "current" Text Object.

.TEXT SET TXT MARGIN:R

Set the Right margin for the text in the "current" Text Object.

.TEXT SET TXT MARGIN:T

Set the Top margin for the text in the "current" Text Object.

.TEXT SET TXT MARGIN:B

Set the Bottom margin for the text in the "current" Text Object.

.TEXT SET TXT ROTATION

Set the rotation angle for the text in the "current" Text Object.

.TEXT SET TXT ALIGN

Set the alignment of the text in the "current" Text Object.

.TEXT SET TXT LAYOUT

Set the layout direction of the text(horizontal or Vertical) in the "current" Text Object.

Topic revision: r72 - 2011-09-27 - JeanNeron

~~Edit~~
~~Attach~~