Purpose
Modifies the Theme Legend window. You can issue this statement from the MapBasic window in MapInfo Pro.
Syntax
Set Legend
[ Window window_id ]
[ Layer { layer_id | layer_name | Prev }
[ Display { On | Off } ]
[ Shades { On | Off } ]
[ Symbols { On | Off } ]
[ Lines { On | Off } ]
[ Count { On | Off } ]
[ Title { Auto | layer_title [ Font... ] } ]
[ SubTitle { Auto | layer_subtitle [ Font... ] } ]
[ Region [ Height region_height [ Units paper_units ] ] ]
[ Region [ Width region_width [ Units paper_units ] ] ]
[ Line [ Width line_width [ Units paper_units ] ] ]
[ Auto Font Size { On | Off } ]
[ Style Size { Large | Small } ]
[ Columns number_of_columns ]
[ Ascending { On | Off } | Order { Ascending | Descending |
Custom } ]
[ Ranges { Auto | [ Font... ]
[ Range { range_identifier | default } ]
range_title [ Display { On | Off } ] }
[ , ... ] ] ]
[ , ... ] window_id is the integer window identifier of a Map window.
layer_id is a SmallInt that identifies a layer of the map.
layer_name is a string that identifies a map layer.
layer_title, layer_subtitle are character strings which will appear in the theme legend.
number_of_columns is a value representing the column width.
region_height is a value representing the new height of a swatch in the map frame of the Legend window. You can specify 8 to 144 points, 0.666667 to 12 picas, 0.111111 to 2 inches, 0.282222 to 5.08 millimeters, or 0.282222 to 5.08 centimeters. If not specified, then the default value of 32 points is used (which can be set as a preference).
region_width is a value representing the new width of a swatch in the map frame of the Legend window. You can specify 8 to 144 points, 0.666667 to 12 picas, 0.111111 to 2 inches, 0.282222 to 5.08 millimeters, or 0.282222 to 5.08 centimeters. If not specified, then the default value of 32 points is used (which can be set as a preference).
line_width is a value representing the new width of a line segment in the map frame of a Legend window. You can specify 12 to 144 points, 1 to 12 picas, 0.666667 to 2 inches, 4.23333 to 50.8 millimeters, or 4.23333 to 50.8 centimeters. If not specified, then the default value of 36 points is used (which can be set as a preference).
paper_units is a string representing a paper unit name: cm (centimeters), mm (millimeters), in (inches), pt (points), and pica.
- 1 inch (in) = 2.54 centimeters , 254 millimeters, 6 picas, 72 points
- 1 point (pt) = 0.01389 inches, 0.03528 centimeters, 0.35278 millimeters, 0.08333 picas
- 1pica = 0.16667 inches, 0.42333 centimeters, 4.23333 millimeters, 12 points
- 1 centimeter (cm) = 0.39370 inches, 10 millimeters, 2.36220 picas, 28.34646 points
- 1 millimeter (mm) = 0.1 centimeters, 0.03937 inches, 0.23622 picas, 2.83465 points
range_title is a text string describing one range in a layer that is shaded by value.
Description
The Set Legend statement controls the appearance of the contents in MapInfo Pro's Theme Legend window. To change the width, height, or position of the Legend window, use the Set Window statement.
Between sessions, MapInfo Pro preserves theme legend settings by storing a Set Legend statement in the workspace file. To see an example of the Set Legend statement, you could create a Map, create a theme legend, save the workspace (for example, LEGEND.WOR), and examine the workspace in a MapBasic text editor window. You could then cut/copy and paste to put the Set Legend statement in your MapBasic program file.
Although MapInfo Pro can maintain a large number of Map windows, only one Theme Legend window exists at any given time. The Theme Legend window displays information about the active Map. Thus, the Set Legend statement's window_id clause identifies one of the Map windows in use, not the Legend window. If no window_id is specified, the statement affects the legend settings for the topmost Map window.
The Layer clause specifies which layer's theme legend should be modified. The Layer clause can identify a layer by its specific number (for example, specify 2 to control the theme legend of the second map layer), by its name, or by specifying Layer Prev. The Layer Prev clause tells MapBasic to modify whatever map layer was last created or modified through a Set Shade statement or Shade statement.
If a Map window contains two or more thematic layers, the Set Legend statement can include one Layer clause for each thematic layer.
The remainder of the options for the Set Legend statement all pertain to the Layer clause; that is, all of the clauses described below are actually sub-clauses within the Layer clause.
The Count clause dictates whether each line of the theme legend should include a count, in parentheses, of how many of the table's records belong to that range. The Shades, Symbols and Lines clauses dictate which types of graphic objects appear in each line of the theme legend. If the statement includes the Shades On clause, each line of the theme legend will include a sample fill pattern. If the statement includes the Symbols On clause, each line of the theme legend will include a sample symbol marker. If the statement includes the Lines On clause, each line of the theme legend will include a sample line style.
The Title clause specifies what title, if any, will appear above the range information in the theme legend. Similarly, the Subtitle clause specifies a subtitle. The title and the subtitle are each limited to thirty-two characters. If a theme legend includes a title, a subtitle, and range information, the objects will appear in that order-the title first, then the subtitle below it, then the range information below the subtitle. If the optional Auto clause is used, the text is automatically generated for each theme.
The Font clause specifies a text style.
The Columns clause allows you to specify the width of the legend.
The Region Height clause specifies a specific height for a swatch in the legend frame of the Legend window.
The Region Width clause specifies a specific width for a swatch in the legend frame of the Legend window.
The Line Width clause specifies a specific width for a line sample in the legend frame of the Legend window.
Auto Font Size enables or disables resizing the legend swatch based on the font size setting.
The Ascending On clause arranges the range descriptions in ascending order. If this optional clause is omitted, the default order of the ranges is descending.
The Ranges clause describes the text that will accompany each line in the theme legend. Each range description consists of a text string (range_title) followed by a Display clause. The Display clause (Display On or Display Off) dictates whether that range will be displayed in the theme legend. Note If the Auto clause is not used, the Ranges clause must include a range_title Display clause for each range in the thematic map, even if some of the ranges are not to be displayed.
If a map layer is a graduated symbols theme, there should be exactly two range_title Display clauses. If a map layer is shaded as a dot density theme, there should be exactly one range_title Display clause. Otherwise, there should be one more range_title Display clause than there are ranges; this is because the theme legend reserves one line for an artificial range known as "all others". The all-others range represents any and all objects which do not belong to any of the other ranges.
The Order and Range clauses will increase the workspace version to the current version. Old workspaces will still parse correctly as there is still support for the original Ascending clause. If the order is not custom, MapInfo Pro will write out the original Ascending clause and NOT increase the workspace version.
The Order clause is another way to specify legend label order of ascending or descending as well as new custom order. However, the original Ascending clause is still available for backwards compatibility. You can use either the Order clause, or the Ascending clause, but not both (both clauses cannot be included in the same MapBasic statement or you will get a syntax error).
The Custom option for the Order clause is allowed only for Individual Value themes. An error will occur if you try to custom order other theme types. The error is "Custom legend label order is only allowed for Individual Value themes."
When the Order is Custom, each range in the Ranges clause must include a range identifier, otherwise a syntax error will occur. The range identifier must come before the range title and Display clause. The range identifier is the same const string or value used by the Values clause in the Shade statement that creates the Individual Value theme. The range identifier for the "all others" category is 'default'.
Every category in the theme must be included, including the default or "all others" category, otherwise an error will occur. The error is "Incorrect number of ranges specified for custom order."
The default or "all others" category may also be reordered, although the best place to place this argument is at the end or beginning of the Ranges clause.
If the range identifier does not refer to a valid category an error will occur. The error is "Invalid range value for custom order."
The Style Size clause facilitates thematic swatches to appear in different sizes.
Example
The following example changes the swatch height to 40 pts.
Set Legend
Window FrontWindow()
Layer 1 Region Height 40 Units "pt"See Also:
Map statement, Open Window statement, Set Map statement, Set Window statement, Shade statementSet Legend Order
The Set Legend statement applies to thematic legends only, but thematic legends can display in the legacy Theme Legend, the Legend Designer, and Layout Designer windows. The Order clause in the Set Legend statement changes the order of legend rows for any thematic legend. You can specify ascending or descending order. Only the Individual Value thematic legend supports a custom order.
As an example, an Individual Value theme (as Layer one on the map) has four ranges, which is four rows in its legend: They are "High", "Moderate", "Low", and "Very High". To display the legend with the ranges in descending alphabetical order, the MapBasic would be:
Set Legend Layer 1 Order DescendingTo customize the order for the ranges to go from "Very High" to "Low", all the ranges must be listed:
Set Legend Layer 1 Order Custom Ranges Range "Very High" auto, Range "High" auto, Range "Moderate" auto, Range "Low" auto, Range default autoRange default auto is the All Others range. The order of the All Others range can also be changed: It is just being shown at the end.