Purpose
The Add Cartographic Frame statement adds cartographic frames to an existing cartographic legend created with the Create Cartographic Legend statement. You can issue this statement from the MapBasic window in MapInfo Pro.
Syntax
Add Cartographic Frame
[ Window legend_window_id ]
[ Custom ]
[ 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 }
[ Position ( x , y ) [ Units paper_units ] ]
[ Using
[ Column { column | object [ FromMapCatalog { On | Off }]} ]
[ Label { expression | default } ]
[ Title [ frame_title ] [ Font... ] ]
[ SubTitle [ frame_subtitle ] [ Font... ] ]
[ Border Pen... ]
[ Style [Font...] [ NoRefresh ]
[ Text { style_name } { Line Pen...
| Region Pen... Brush...
| Symbol Symbol... } ]
[ , ... ]
]
[ , ... ]legend_window_id is an integer window identifier that you can obtain by calling the FrontWindow() function and WindowID() function.
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 (e.g., 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.
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
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, or the object column (meaning that legend styles are based on the unique styles in the mapfile). The default is 'object'.
style_name is a string which displays next to a symbol, line, or region in a custom frame.
Description
If the Custom keyword is included, then each frame section must include a Position clause. If Custom is omitted and the legend is laid out in portrait or landscape, then the frames will be added to the end.
The Position clause controls the frame's position on the legend window. The upper left corner of the legend window has the position 0, 0. Position values use paper unit settings, such as "in" (inches) or "cm" (centimeters) (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.You can override the current paper units by including the optional Units subclause within the Position clause.
The defaults in this statement apply only to the frames being created in this statement. They have no affect on existing frames. Frame defaults used in the Create Cartographic Legend statement have no affect on frames created in this statement.
When you save to a workspace, the FromMapCatalog OFF clause is written to the workspace when specified. This requires the workspace version increasing to 800. If the FromMapCatalog ON clause is specified, we do not write it to the workspace since it is default behavior. This lets us avoid increasing the workspace version.
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).
Label is 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.
The Style clause and the NoRefresh keyword allow you to create a custom frame that will not be 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 and appropriate Line, Region, or Symbol clause.
See Also:
Create Cartographic Legend statement, Set Cartographic Legend statement, Alter Cartographic Frame statement, Remove Cartographic Frame statement