CreateFigure()

Summary

Creates a new window containing a figure.

Changes

Added Prism Map type to Version 5.0. Added Label Angle option to Version 2014.

Syntax

window_name = CreateFigure(string figure_name, string type, array options)

Argument	Contents
figure_name	The desired name for the figure window
type	The figure type: Chart or Prism Map

Options	Type	Contents
Activate Macro	String	The name of a macro that is called whenever the window is activated
Aspect Ratio	2 integers	The aspect ratio of the window (height, width)
Click Macro	String	The name of a macro that is called when the user double-clicks on the window
Close Macro	String	The name of a macro that is called when the user closes the window from the system menu
Context Menu	String	The name of the menu resource to use to display a custom context menu when there is a right click on the window
Done Macro	String	The name of a macro that is called after the window is closed
Figure Background Color	Color	The background color of the window (defaults to white)
Figure Background Style	Fillstyle	The background fillstyle of the window (defaults to none)
Footnote Font	String	The font used for the diagram's footnote
Footnote Text	String	The text of the diagram's footnote, located at the bottom right of the window
Menu	String	The menu associated with the window
Position	2 integers	The screen location of the window (x, y)
Size	2 integers	The screen size of the window (x, y)
Title Font	String	The font used for the diagram's title
Title Text	String	The text of the diagram's title, centered above the figure
Toolbar	String	The toolbar associated with the map window

The following options apply only to charts:

Options for Charts	Type	Contents
3D	Boolean	Whether to display the chart using a 3-dimensional style (defaults to "False")
Axis Font	String	The font used for the axes' labels
Axis Labels	Array	The text of the axes' labels ({string primary, string secondary (optional)})
Chart Type	String	The type of chart: "Area", "Bar" (default), "Line", "Pie", "XY"
Colors	Array	The list of colors used
Explode	Array	Whether to explode the data element. Each array element is a boolean
Fill Styles	Array	The list of fill styles used to display lines (will wrap around to the beginning of the list if not enough styles were specified)
Format	String	The format string used when displaying values (defaults to "*.##"); for more information, see Format().
Grouped	Boolean	Whether the histo bars should be grouped rather than stacked (defaults to "False")
Hash marks	Real	The frequency of hash marks
Horizontal	Boolean	Whether the chart should be oriented horizontally instead of vertically (defaults to "False")
Icon Colors	Array	The list of colors used to display icons (will wrap around to the beginning of the list if not enough colors were specified)
Icons	Array	The list of icons specifications (defined below, will wrap around to the beginning of the list if not enough specifications were provided)
Label Angle	Real	The angle to rotate the x-axis labels
Label Bars	String	Whether to label with values (defaults to "False")
Label Font	String	The font used for labels
Label Values	Integer	The frequency of labels (2 = every other hash mark is labeled)
Labels	Array	The list of labels used. Each element can be either a string or a numeric value
Legend	Array	The list of labels used for the legend. Each element can be either a string or a numeric value
Line Styles	Array	The list of line styles used to display lines (will wrap around to the beginning of the list if not enough styles were specified)
Line Widths	Array	The list of numeric widths used to display lines (will wrap around to the beginning of the list if not enough styles were specified)
Maximum	Real	Maximum data value to use (defaults to positive infinity)
Minimum	Real	Minimum data value to use (defaults to negative infinity)
Sort	String	The method used to sort the data: "Alphabetic" (by label), "Decreasing" (by value), "Increasing" (by value), "None" (default), or "Reverse Alphabetic" (by label)
Values	Array	The list of values used to create the chart (required). Each element is either a numeric value or an array of numeric values
X Hash Marks	Real	The frequency of x-axis hash marks for scatter plots
X Maximum	Real	Maximum x value to use for scatter plots (defaults to positive infinity)
X Minimum	Real	Minimum x value to use for scatter plots (defaults to negative infinity)

Icon Element	Type	Contents
1	String	A string indicating the type of icon. This string must be "Font Character"
2	String	The name of a TrueType font (including size and style)
3	Integer	The index of a character in the font

The following options apply to prism maps:

Options for Prism Maps	Type	Contents
View	String	The name of the view containing the features to be mapped; can be of the form "viewname," "view\|set," or "map\|view\|set"
Field	String	The name of the field containing the height values
Log	Boolean	"True" to use a logarithmic scale (default is "False")
Exaggeration	Real	A value greater than or equal to zero, indicating the vertical exaggeration
Height Range	Real	The range of heights, from 1 to 100
Scope	Scope	The scope of the prism map
Random Colors	Array	An array of random colors
Start Color	Color	The starting color of a color ramp
End Color	Color	The ending color of a color ramp
Color Spiral	Array	An options array describing the interpolation of colors for a color ramp; for more information, see GeneratePalette()
Clock Angle	Real	Clockwise viewing angle (0 from the south, 90 from the west, etc.)
Up Angle	Real	Hemispheric viewing angle (90 from straight above, 0 from along the surface)
Scale	Real	A number such that 1:scale is the map scale at elevation 0 if viewed from above
Title Text	String	The caption above the prism map
Title Font	String	The font used for the title, such as "Arial\|Bold\|16"
Footnote Text	String	The text of the footnote, located at the bottom right of the prism map
Legend Style	String	"Back Wall" for a legend to show heights around the back walls, or "None" for no legend (the default)
Legend Font	String	The font used for the title, such as "Arial\|Bold\|8"
Legend Format	String	The format string for legend numbers; for more information, see Format().

Returns

The actual name of the figure window.

Notes

Footnotes and titles are omitted by default. Both the text and font must be specified for a footnote or a title before the item will be displayed.
The position and size of the window are expressed as percentages of the Maptitude frame.
The attached menu and toolbar are automatically displayed whenever the figure window is activated.
If the menu, toolbar, activate macro, close macro, or click macro is not specified, CreateFigure() uses the default specified with SetDefaults(). If a figure window specific default was not specified with SetDefaults() then CreateFigure() uses the generic default.
The Label Angle rotation is in degrees, from -90 to 90. When the angle is zero, no rotation takes place and the text is centered under the data point. When the angle positive, each data point label is aligned by anchoring by the end of the text beneath the data point, with the text rotated counterclockwise by that many degrees from the x-axis. For a negative angle, the beginning of the text is anchored beneath the data point and the text is rotated by that many degrees clockwise.
If the Random Colors option is used for a prism map, the prisms will be colored by randomly choosing one color out of the array for each surface.
If the Start Color and End Color options are used for a prism map, color is interpolated between the two: The lowest surface will use Start Color and the highest surface will use End Color. The Spiral option can be used to indicate the interpolation; for more information, see GeneratePalette().

Error Codes

Error Type	Meaning
Error	An invalid option was specified

Function	Summary
OpenFigure()	Creates a figure window from a file
OpenFigureFromAnnotation()	Creates a new figure window from a figure that appears in a layout
SaveFigure()	Saves a figure to a file