CreateTheme()

Summary

Creates a color or pattern theme on the current layer.

Changes

Optimal option added to Version 5.0.

Syntax

theme_name = CreateTheme(string identifier, string field_spec, string method, integer num_classes, array options)

Returns

A string indicating the actual name of the theme.

Notes

• CreateTheme() creates a theme on the current layer.

• Only the Categories and Manual methods are valid for a string field.

• If many features have identical values for the field used in the theme, the classes may not conform to the input specifications.

• If the values, when using the Counts method, sum to more than the total number of features, or if the values, when using the Percents method, sum to more than 100%, the excess is ignored.

• The num_classes parameter is the number of classes excluding the "Other" class; added if the Other option is "True" (the default).

• For the Quantiles method, if the values of the num_classes parameter is larger than the number of features, the number of classes will be reduced, since each class must contain at least one feature.

• CreateTheme() scans the data for the layer to find appropriate minimum, maximum, and class values for a numeric field, or to identify the values that appear in the data for a string field.

• When the Pretty Values option is "True" the minimum and maximum values are rounded as far as possible, without affecting the assignment of features to classes.

• For the Manual method, no statistics are generated when the Statistics option is "False".

• The color and style of any theme class can be set regardless of whether the theme is a color theme or a pattern theme (as specified by the Style option). However, you cannot display two class themes of the same type at the same time.

• The following options apply only to themes on numeric fields: Direction, Force Value, Maximum Value, Minimum Value, Include Maximum, Include Minimum, Pretty Values, Rate, Scale, Sort Order, Type, and Zero.

• If the Retain Values option is set to "True" then the memory used should be freed either by a call to ClearThemeValues() or by a subsequent call to CreateTheme() or TestTheme().

• The icons used for a color theme for a point layer are the font icons for the classes in the pattern theme. If there is no pattern theme, the font icon for the layer is used. However, with SetThemeIcons() you can set different font icons for some or all of your color theme classes, which will override the font icons for the pattern theme or the font icon for the layer. To have a bivariate map for a point layer, do not set font icons for the color theme.

• After creating the theme, you may need to set theme styles; for more information, see Theme Styles.

• To display the theme, call ShowTheme(); for more information, see Themes.

Examples

// An income theme with eight classes
thm1 = CreateTheme("Income Theme", "County.Income", "Quantiles", 8, )
//This theme has a break in class values at $30,000, and the low and high values are rounded
thm2 = CreateTheme("Income Theme", "County.Income", "Quantiles", 8, {
{"Force Value", 30000},
{"Pretty Values", "True"}})
//This theme has classes that are created manually
thm3 = CreateTheme("Sales Theme", "Regions.Sales", "Manual", 5, {
{"Values", {
{0, "True", 1000, "False"},
{1000, "True", 2500, "False"},
{2500, "True", 10000, "False"},
{10000, "True", 25000, "False"},
{25000, "True", 100000, "True"}}
}})
//This theme has classes containing the top ten; second ten; etc.
thm4 = CreateTheme("Sales Theme", "Customer|Sales", "Counts", 5, {
{"Values", {10, 10, 10, 10, 10},
{"Sort Order", "Descending"}
}})

Error Codes

See Also