At least one FRAME_FROM_LAYER_CLAUSE is required. It sets the style and display of a frame in a Legend window.
Syntax
Create Designer Legend
[ From Window map_window_id ]
[ WINDOW_CLAUSES ]
[ DEFAULT_FRAME_CLAUSES ]
[ LEGEND_TEXT_FRAME_CLAUSE ]
[ FRAME_FROM_LAYER_CLAUSE ]Where FRAME_FROM_LAYER_CLAUSE is:
Create Designer Legend
[ From Window map_window_id ]
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 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 from the Default Frame Subtitle clause (see Default Frame Settings).
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
At least one Frame From Layer clause is required. Each Frame From Layer clause represents one legend frame that will be created in the Legend window.
All clauses pertaining to the Legend window settings and default settings must proceed the first Frame clause.
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 alongside 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.
Examples
Open Table ApplicationDirectory$() + "MyTable.tab" As mytable
Open Table ApplicationDirectory$() + "States.tab" As states
Open Table ApplicationDirectory$() + "City_125.tab" As cities
Open Table ApplicationDirectory$() + "Us_hiway.tab" As hiway
Map From cities, hiway, states, mytable
Create Designer Legend From Window FrontWindow()
Position (8, 0) Units "in"
Width 3 Units "in"
Height 6 Units "in"
Window Title "Legend Designer Window Test"
Custom
Default Frame Title "# Legend" Font ("Calibri",1,12,16711680)
Default Frame Subtitle "#" Font ("Arial",2,10,255)
Default Frame Style "%" Font ("Lucida Calligraphy",0,8,16732240)
Frame From Layer Cities
Using column object
label default
Position (.5, 0) Units "in"
Subtitle "125 Largest Cities"
Frame From Layer hiway
Using column object
label default
Position (.5, .75) Units "in"
Title "US Highways"
Subtitle "Interstates"
Frame From Layer states
Using column object
label default
Position (.5, 1.5) Units "in"
Title "United States"
Subtitle "State Boundaries"
Frame From Layer mytable
Using column object
label default
Position (.5, 2.5) Units "in"
Title "MyTable Objects"
Subtitle "Special Objects"
Columns 4 The following example shows how to use the Create Designer Legend statement for customizing the order of legend rows. Each Text clause describes a legend row and the rows are saved to the workspace in their default order where each Text clause is numbered starting with one (1) and increasing.
Create Designer Legend Frame From Layer 1
Order Custom 2, 3, 4, 1
Style Font ("Arial",0,8,0)
Text "LIBRARY"
Symbol (41,8388608,12,"MapInfo Miscellaneous",0,0)
Text "PRE-SCHOOL - PUBLIC"
Symbol (38,16711935,12,"MapInfo Real Estate",0,0)
Text "PRIMARY SCHOOL - PRIVATE"
Symbol (38,32768,12,"MapInfo Real Estate",0,0)
Text "PRIMARY SCHOOL - PUBLIC"
Symbol (38,32768,12,"MapInfo Real Estate",0,0)The Order Custom clause above applies a custom order to the rows by describing how to arrange row IDs. Order Custom 2,3,4,1 says the legend starts with row number two (2), followed by three (3), and four (4), with the first Text clause at the end like this:
- 2. Text "PRE-SCHOOL - PUBLIC" Symbol (38,16711935,12,"MapInfo Real Estate",0,0)
- 3. Text "PRIMARY SCHOOL - PRIVATE" Symbol (38,32768,12,"MapInfo Real Estate",0,0)
- 4. Text "PRIMARY SCHOOL - PUBLIC" Symbol (38,32768,12,"MapInfo Real Estate",0,0)
- 1. Text "LIBRARY" Symbol (41,8388608,12,"MapInfo Miscellaneous",0,0)
The resulting legend text will look like this:
- PRE-SCHOOL - PUBLIC
- PRIMARY SCHOOL - PRIVATE
- PRIMARY SCHOOL - PUBLIC
- LIBRARY