TheAdd Designer Frame statement adds legend frames to an existing Legend window created with the Create Designer Legend statement. You can issue this statement from the MapBasic window in MapInfo Pro.
Syntax
Add Designer Frame
[ Window legend_window_id ]
[ Custom ]
Frame From Layer { map_layer_id | map_layer_name }
[ Position ( x, y ) [ Units paper_units ] ]
[ Title { frame_title [ Font... ] } ]
[ SubTitle { frame_subtitle [ Font... ] } ]
[ Columns number_of_columns ] |
[ Height frame_height [ Units paper_units ] ]
[ Border Pen .... ] [ Brush ... ]
[ Priority priority_n ]
[ Name frame_name ]
[ 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 } ]
[ Order { Default | Ascending | Descending |
{ Custom id | id : id [ , id | id : id ... ] ... } } ]
[ Using
[ Column { column | Object } [ FromMapCatalog { On | Off } ] ]
[ Label { expression | Default } ] ]
[ Display { Gap | Palette | Bar
[ [ Thickness t_value ] [ Length l_value ]
[ Units paper_units ] [ Horizontal | Vertical ] ] } ]
[ Filter Max max_value ]
[ Sort Alpha ]
[ Into ID frame_id ]
[ Style [ Font...] [ Norefresh ] [ Count { On | Off } ]
[ Text { style_name }
{ [Line Pen...] | [ Region Pen... ] [ Brush... ] | [ Symbol... ] |
Collection [ Symbol... ] [ Line Pen... ] [ Region Pen... ] [ Brush... ] }
[ Count count_value ]
[ Display { On | Off } ] ]
[ Text . . .] ]map_window_id is an integer window identifier which you can obtain by calling the FrontWindow() function and WindowID() function. If this identifier is for a map within a Layout window, then the legends are created in the window.
map_layer_id or map_layer_name identifies a map layer; This 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.
paper_units is a string representing a paper unit name: cm (centimeters), mm (millimeters), in (inches), pt (points), and pica. For a list of paper unit names, see Set Paper Units statement.
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 default frame subtitle stored with the window when it was created.
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 default frame subtitle stored with the window when it was created.
number_of_columns is the number of columns to show in a frame.
frame_height this is used in place of the Column clause when the user resizes a legend frame. The height of the frame is in paper units. This is written to the WOR file when the frame has been manually resized.
priority_n is an integer value indicating the Z-Order value of the legend when it is embedded in a Layout window.
frame_name is a string representing the name for this legend frame embedded in a Layout window.
region_height and region_width a values representing the new height and width of region swatches. 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.
line_width is a value representing the width of a line swatch. 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.
column is an attribute column name from the map layer's table.
expression is a valid MapBasic expression.
t_value is the thickness of the color bar for the raster legend. The units are inches unless the Units clause is included.
l_value is the length of the color bar for the raster legend. The units are inches unless the Units clause is included.
max_value is the maximum number of colors to display in the raster legend.
frame_id is the frame identifier (ID from 1 to the total number of frames) for an empty layout frame on the current layout window.
style_name is a string which displays next to a symbol, line, or region in a custom legend.
count_value is a count value for a particular row in a raster legend.
Description
The default properties set in the Create Designer Legend statement are used when adding new frames. You override these default properties when you explicitly set properties for the frames that you are adding. Unlike the Add Cartographic Frame statement, the Add Designer Frame statement supports a Columns clause that lets you specify how many columns to use in a legend frame.
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 Frame From Layer clause represents one legend frame that will be created in the Legend window. Use a (SmallInt) value, such as one (1) to specify the top map layer other than the Cosmetic layer, or a string representing the layer name in an existing map. For a theme layer you must specify the map_layer_id.
The Position clause sets the position of the frame if Custom is specified at the window level of the MapBasic statement. The x coordinate measures from the left of the Legend window, and the y coordinate measures from the top of the Legend window. The origin (0,0) is in the top-left of the Legend window.
If a frame Title exists, it overrides the Default Frame Title. If the frame title includes a Font, then the font overrides the default frame title font if it exists.
If a frame Subtitle exists, it overrides the Default Frame Subtitle. If the frame subtitle includes a Font, then the font overrides the default frame subtitle font if it exists.
The Height clause is used in place of the Columns clause when the user resizes a frame. If both are present, then the Columns clause is used.
The Columns or Height clauses also apply to map and thematic legends. However, all other thematic legend properties must be specified using the Set Legend statement.
The Border clause is used only to provide border and background styles for the legend when it is embedded in a Layout window.
Pen is followed by a valid Pen clause. This clause is designed to turn on (solid) or off (hollow) and set the color of the border of the frame when it is embedded in a Layout window.
Brush is a valid Brush clause. Only Solid brushes are allowed. While values other than solid are allowed as input without error, the type is always forced to solid. This clause is used only to provide the background color for the frame when it is embedded in a Layout window.
The Priority clause assigns a Z-Order to the legend frame when it is embedded in a Layout window.
The Name clause assigns a name to the legend when it is embedded in a Layout window.
The Region Height clause specifies a specific height for swatches in the legend and overrides the frame default setting.
The Region Width clause specifies a specific width for swatches in the legend and overrides the frame default setting.
The Line Width clause specifies the width of line swatches in the legend and overrides the frame default setting.
Auto Font Size enables or disables resizing legend swatches based on the Style font size setting.
The Order clause adds the ability to sort or customize the order of rows in map legends. You can sort rows by style label or by defining your own order. The sort order options are Default, Ascending, Descending, or Custom. The Order clause is only written to a workspace if the legend is sorted ascending, descending, or custom.
A Default sort order is the order the Create Legend wizard creates the legend rows. If you create a legend based on unique styles, this will be the order of those styles, which then display as rows in the map legend. If specifying Custom sort order, the id values are row ids starting with one (1), moving from top to bottom. When looking at the list of rows in the Legend Frame Properties dialog box, the first row in the list has id equal to one (1) and so on down the list. For more details, see Custom Order Options and the Alter Designer Frame statement custom order Options.
Into ID lets you insert a legend into an empty layout frame. If the frame is not empty, then an error results. If the frame_id is 1 and the frame is not empty, then the message "Layout frame 1 must be empty" results. Into ID is optional and any legends created or added without it are auto-positioned along side the map, which is the normal behavior. The Map window must be on the same layout page as its legend: inserting a legend on to a different layout page or when the map is not in the Layout window causes an error, "The parent Map must be embedded on the current page of a Layout window." This error ID is 1067.
When using the Into ID clause, other clauses are ignored and do not generate errors. These clauses are, Position, Units, Height, Border, Brush, Priority, and Name. The size of the frame is set to ensure the best fit of the legend in it.
The Using clause determines how a legend for a vector layer is created. It refers to table elements through the Column and Label clauses.
If Column is defined, column is the name of an attribute column in the frame layer's table or Object denotes the object column (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 MapBasic expression, or Default (so 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 Display { Gap | Palette | Bar } clause only applies to raster legends.
Display Bar displays a continuous raster legend using a color bar. This clause also has options to set the bar size and orientation: Thickness, Length, Units, and orientation (Horizontal or Vertical). Units is optional. If it is not provided, MapInfo Pro uses inches. When either thickness, length, or orientation are missing, MapInfo Pro uses default values set by the Default Frame Bar clause.
Display Palette displays a continuous raster legend as solid color swatches with labels. The size of the swatches are dependent on region width and height settings either set per frame, or as default settings.
- Continuous, MapInfo Pro uses the Display Bar clause when there are more than 20 colors, otherwise it uses Display Palette.
- Classified, MapInfo Pro uses the Display Gap clause.
The Filter Max clause specifies the maximum number of rows or colors created for the raster legend. This clause is optional and only valid for raster legend frames. The default value is 100. If you do not use this clause, then MapInfo Pro displays 100 colors in the raster legend. Allowable values are one (1) to 1600.
The Sort Alpha clause is used with a classified raster legend frame. It sorts labels alphabetically.
The Style clause with the NoRefresh keyword lets you create a custom legend that will not be overwritten when the legend is refreshed. However, the Style clause must contain your custom list of row definitions for the styles displayed in the legend. This is done with the Text and appropriate Line, Region, Symbol, or Collection clauses.
The Font clause specifies a text style for each row's label and overrides the Default Frame Style font.
The Count { On | Off } applies only to raster legends and controls whether record counts should be shown per row. The default is Off. This is ignored when the raster legend displays a color bar.
Each legend row starts with the Text clause followed by Line, Region, Symbol, or Collection clauses.
At the end of each Text clause is the optional Count clause, which applies only to raster legends. If the raster layer has per-record counts, they will be persisted for each row in the legend. This should not be modified, so the Alter Designer Frame statement does not support changing this value.
Also at the end of each Text clause is the optional Display clause. Display On makes the row visible. Display Off makes the row invisible. If the Display clause is absent, then the row displays. The Display clause is only written to a workspace file for rows that are not visible in a legend frame.
Take note of the following:
- When adding legend frames from MapInfo Pro, new frames are selected.
- When adding legend frames from MapBasic, new frames are not selected and the previous selection remains unchanged.
- The LayoutInfo( ) function includes theme legends in its frame count.
Examples
You can get an count of open document windows using NumAllWindows( ) function, then loop through them using WindowID( ) function or WindowInfo( ) function to find the legend window by type and its window ID to use with the Add Legend Designer statement.
Dim i, wndLegend as integer
for i = 1 to NumWindows()
If WindowInfo(WindowID(i), WIN_INFO_TYPE) = WIN_LEGEND_DESIGNER then
wndLegend = WindowInfo(WindowID(i), WIN_INFO_WINDOWID)
end if
nextThis example adds frames.
Add Designer Frame Window wndLegend Frame From Layer 2 Columns 2To get the window identifier use the following where window_id is an integer window identifier for a Layout window and frame_id is a number that specifies which frame within the Layout window you want to query.
LayoutItemInfo(window_id, frame_id, 10)For example, if a layout has one map frame and one or more legends, then the map frame is frame_id 1 and the first legend is 2. The following will return window identifier for the Legend window where 2 is a legend frame:
Dim LD_window as Integer
LD_window = LayoutItemInfo(window_id, 2, 10)You can use the results of the above in a statement to add legends:
Add Designer Frame Window window_id Frame From Layer . . .See Also:
Create Designer Legend statement, Set Designer Legend statement, Add Designer Frame statement, Add Designer Text statement, Add Image Frame statement, Add Image Page statement, Alter Designer Frame statement, Remove Designer Frame statement