Purpose
Creates and displays cartographic style legends as well as theme legends for an active map window. You can issue this statement from the MapBasic window in MapInfo Pro.
Syntax
Create Cartographic Legend
[ From Window map_window_id ]
[ Behind ]
[ Position ( x, y ) [ Units paper_units ] ]
[ Width win_width [ Units paper_units ] ]
[ Height win_height [ Units paper_units ] ]
[ Window Title { legend_window_title }
[ ScrollBars { On | Off } ]
[ Portrait | Landscape | Custom ]
[ Style Size { Small | Large }
[ Default Frame Title { def_frame_title } [ Font... ] } ]
[ Default Frame Subtitle { def_frame_subtitle } [ Font... ] } ]
[ Default Frame Style { def_frame_style } [ Font... ] } ]
[ Default Frame Border Pen [ [ pen_expr ]
Frame From Layer { map_layer_id | map_layer_name
[ Using
[ Column { column | Object } [ FromMapCatalog { On | Off }]]
[ Label { expression | Default } ]
[ Position ( x, y ) [ Units paper_units ] ]
[ Title { frame_title [ Font... ] }
[ SubTitle { frame_subtitle [ Font... ] } ]
[ Border Pen pen_expr ]
[ Style [ Font...] [ Norefresh ] [ Text { style_name }
{ Line Pen... | Region Pen... Brush...| Symbol Symbol... } |
Collection [ Symbol ... ]
[ Line Pen... ] [ Region Pen... Brush ...] } ]
[ , ... ]map_window_id is an integer window identifier which you can obtain by calling the FrontWindow() function and WindowID() function.
x states the desired distance from the top of the workspace to the top edge of the window.
y states the desired distance from the left of the workspace to the left edge of the window.
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
win_width is the desired width of the window.
win_height is the desired height of the window.
legend_window_title is a string expression representing a title for the window, defaults to "Legend of xxx" where xxx is the map window title.
def_frame_title is a string which defines a default frame title. It can include the special character "#" which will be replaced by the current layer name.
def_frame_subtitle is a string which defines a default frame subtitle. It can include the special character "#" which will be replaced by the current layer name.
def_frame_style is a string that displays next to each symbol in each frame. The "#" character will be replaced with the layer name. The % character will be replaced by the text "Line", "Point, "Region", as appropriate for the symbol. For example, "% of #" will expand to "Region of States" for the STATES.TAB layer.
pen_expr is a Pen expression, for example, MakePen( width, pattern, color ). If a default border pen is defined, then it will be become the default for the frame. If a border pen clause exists at the frame level, then it is used instead of the default.
map_layer_id or map_layer_name identifies a map layer; can be a SmallInt (for example, use 1 to specify the top map layer other than Cosmetic) or a string representing the name of a table displayed in the map. For a theme layer you must specify the map_layer_id.
frame_title is a string which defines a frame title. If a Title clause is defined here for a frame, then it will be used instead of the def_frame_title.
frame_subtitle is a string which defines a frame subtitle. If a Subtitle clause is defined here for a frame, then it will be used instead of the def_frame_subtitle.
column is an attribute column name from the frame layer's table.
style_name is a string which displays next to a symbol, line, or region in a custom frame.
Description
The Create Cartographic Legend statement allows you to create and display cartographic style legends as well as theme legends for an active map window. Each cartographic and thematic styles legend will be connected to one, and only one, Map window so that there can be more than one Legend window open at a time.
You can create a frame for each cartographic or thematic map layer you want to include on the legend. The cartographic and thematic frames will include a legend title and subtitle. Cartographic frames display a map layer's styles; legend frames display the colors, symbols, and sizes represented by the theme. You can create frames that have styles based on the Map window's style or you can create your own custom frames.
At least one Frame clause is required.
All clauses pertaining to the entire legend (scrollbars, width, etc.) must proceed the first Frame clause.
The From Layer clause must be the first clause after the Frame clause.
The optional Behind clause places the legend behind the Thematic Map window.
The optional Position clause controls the window's position on MapInfo Pro's workspace. The upper left corner of MapInfo Pro's workspace has the position 0, 0. The optional Width and Height clauses control the window's size. Window position and size values use paper units settings, such as "in" (inches) or "cm" (centimeters). For details about paper units, see Set Paper Units statement. MapBasic has a current paper units setting, which defaults to inches; a MapBasic program can change this setting through the Set Paper Units statement. A Create Cartographic Legend statement can override the current paper units by including the optional Units subclause within the Position, Width, and/or Height clauses.
Use the ScrollBars clause to show or hide scroll-bars on a Map window.
Portrait or Landscape describes the orientation of the legend frames in the window. Portrait results in an orientation that is down and across. Landscape results in an orientation that is across and down.
If Custom is specified, you can specify a custom Position clause for a frame.
The Position clause at the frame level specifies the position of a frame if Custom is specified.The x coordinate measures from the left of the legend window, and the y coordinate measures from the bottom of the legend window (the origin (0,0) is in the bottom-left of the legend window).
The optional Style Size clause controls the size of the samples that appear in legend windows. If you specify Style Size Small, small-sized legend samples are used in Legend windows. If you specify Style Size Large, larger-sized legend samples are used.
The Position, Title, SubTitle, Border Pen, and Style clauses at the frame level are used only for map layers. They are not used for thematic layers. For a thematic layer, this information is gotten automatically from the theme.
The Font clause specifies a text style. If a default frame title, subtitle, or style name font is defined, then it will become the default for the frame. If a frame level Title, Subtitle, or Style clause exists and includes a Font clause, then the frame level font is used. If no font is specified at any level, then the current text style is used and the point sizes are 10, 9, and 8 for title, subtitle and style name.
The Style clause and the NoRefresh keyword allow you to create custom frames that are not overwritten when the legend is refreshed. If the NoRefresh keyword is used in the Style clause, then the table is not scanned for styles. Instead, the Style clause must contain your custom list of definitions for the styles displayed in the frame. This is done with the Text clause and appropriate Line, Region, or Symbol clause. Multipoint objects are treated as Point objects.
Collection objects are treated separately. When MapInfo Pro creates a Legend based on object types, it draws Point symbols first, then Lines, then Regions. Collection objects are drawn last. Inside collection objects the order of drawing is point, line, and then region samples.
If Column is defined, column is the name of an attribute column in the frame layer's table, or Object denotes the object column (meaning that legend styles are based on the unique styles in the map file). The default is Object.
FromMapCatalog ON retrieves styles from the MapCatalog for a live access table. If the table is not a live access table, MapBasic reverts to the default behavior for a non-live access table instead of throwing an error. The default behavior for a non-access table is FromMapCatalog Off (for example, map styles).
FromMapCatalog OFF retrieves the unique map styles for the live table from the server. This table must be a live access table that supports per record styles for this to occur. If the live table does not support per record styles than the behavior is to revert to the default behavior for live tables, which is to get the default styles from the MapCatalog (FromMapCatalog ON).
If a Label is defined, specify expression as a valid expression, or Default (meaning that the default frame style pattern is used when creating each style's text, unless the style clause contains text). The default is Default.
Initially, each frame layer's TAB file is searched for metadata values for the title, subtitle, column and label. If no metadata value exists for the column, the default is Object. If no metadata value exists for Label, the default is the default frame style pattern. If legend metadata keys exist and you want to override them, you must use the corresponding MapBasic syntax.
Example
The following example shows how to create a frame for a Map window's cartographic legend. Legend windows are a special case: To create a frame for a Legend window, you must use the Title clause instead of the From Window clause.
Dim i_layout_id, i_map_id As Integer
Dim s_title As String
' here, you would store the Map window's ID in i_map_id,
' and store the Layout window's ID in i_layout_id.
' To obtain an ID, call FrontWindow() or WindowID().
s_title = "Legend of " + WindowInfo(i_map_id, WIN_INFO_NAME)
Set CoordSys Layout Units "in"
Create Frame
Into Window i_layout_id
(1,2) (4, 5)
Title s_title This creates a frame for a Cartographic Legend window. To create a frame for a Thematic Legend window, change the title to the following.
S_title="Theme Legend of " + WindowInfo (I_map_id, WW_INFO_NAME)See Also:
Set Cartographic Legend statement, Alter Cartographic Frame statement, Add Cartographic Frame statement, Remove Cartographic Frame statement, Create Legend statement, Set Window statement, WindowInfo() function