Legend Dialog

The Legend dialog allows simple customization of legends that are automatically created for map windows (including also drawing, label, and image windows) and for layout windows.   The same dialog is used for simple configuration of automatically created legends both in map windows and in layout windows, even though the two different windows have significantly different capabilities for more advanced configuration.

Launching the Legend Dialog for a Map Window

How we launch the Legend dialog depends on the context in which we are working with legends.   Automatic legends in map windows have limited configuration options, to keep legending in map windows as simple and easy as possible.   



To turn on a legend in a map window, we simply turn on the virtual Legend layer that is in the Layers pane for every map window.



That immediately pops open the virtual layer that provides a legend, with the legend configured using default settings.



To configure the legend in a map window, with the focus on the opened map window, launch the Legend dialog by double-clicking the Legend virtual layer in the Layers pane.   



That opens the Legend dialog for the legend in the map window.

Launching the Legend Dialog for a Layout Window

Layout windows have a more complex structure than map windows, since layouts can consist of very many frames that are positioned and sized differently.



To add a legend frame to a layout, To create a legend frame, open a layout, choose the Create Legend tool from the drop-down menu for the cursor mode button in the main toolbar, and then in the layout window click the approximate center of the legend frame you would like to create.   



A legend frame appears at that location with a default legend in the frame. The legend frame is already picked, ready to edit, as if we had alt-clicked the frame.  If the topmost component frame under the new legend frame contains content from a map, drawing, labels, or image component, and that component has had a legend created and customized for it in the component's window, the legend will use the customization done for the legend in that component window.


The Info pane pops open to the Style tab so we can configure the Legend.



Configure parameters for the legend by clicking the [...] browse button, which launches the Legend dialog.



That opens the Legend dialog for the legend frame in the layout window.  


The Legend dialog for legends in layouts is identical to the Legend dialog for map windows, except that the layout version has no Apply button and no Margin and Size controls, since those are handled by controls in the Info pane for legends or, in the case of Size, by directly resizing the legend frame in the layout.



The Legend dialog allows setting the following parameters:


(Preview pane)

Shows a preview of the current settings used in the dialog.  The background color is light blue by default, to allow either very light or dark shapes to be visible.   Change the background color of the preview pane by clicking the square box in the upper right corner of the preview pane.


The preview pane shows a schematic representation of a legend that includes typical elements which can be configured in the Legend dialog.  It does not show the actual legend being configured, since legends are usually too large to fit into the preview pane.

(Styles gallery)

Choose a legend style from the gallery.   At the present time, the gallery provides a single, plain style.  from a gallery of popular shapes. Hovering the mouse over a style will show the name of that style in a tooltip.

Foreground and stroke color for style and text.

Fill color.

Buttons that show a small "box" sub-icon indicate that color has been changed from the default.


Stroke width for the style, currently setting the width of the legend border.


Text alignment (right, center, left) for legend entries that are entirely text, such as titles. The Cities : Population entry in the preview pane is an example.


Text alignment (right, center, left) for legend entries that have a single sample, such as layers that are not thematically formatted. Text in the Roads, Lakes, and Names entries in the preview pane provides examples.


Text alignment (right, center, left) for legend entries that have multiple samples, such as thematically formatted layers.  Text next to the magenta circles under the Cities : Population layer provides examples.

Font for text. Fully configurable for typeface, effects, bold, etc.

Font size for text.


For maps, a combination of left, center or right horizontal position and top, center, or bottom vertical position, to place the legend in any of nine possible positions within the map window.  The default is the left bottom corner.  


For layouts, a choice of top, center, or bottom vertical position within the frame.  The default is the center of the frame.  


Appears for maps but not for legends in layouts: The horizontal and vertical space between the legend shape and the map's edges.


Appears for maps but not for legends in layouts: The width in points of the legend.


The distance in points between the samples and text of a legend entry and the surrounding legend border. Default is 3 points.  Increasing the padding provides more space between the content of a legend's entries and the borders.


Appears for maps but not for legends in layouts:  Press to apply the current dialog settings to the map.   For legends in layouts, press the OK button and then the Update Frame button in the Info pane.


In addition to the above settings, the composition of a legend will be influenced by Legend Mode settings in the Layers pane.  Legend mode settings determine which layers in a map will appear in the legend and whether, in the case of thematically formatted layers, if they will appear as single line samples or multiple line samples.

Example: Customize a Legend in a Map Window

We will work with a legend in a map window where the Layers pane has been used to specify a Legend Mode of auto short for the buildings layer, so it only appears as a single line entry.  This reduces the size of the legend so it can fit within the illustrations.


With the focus on the map window, in the Layers pane we turn on the Legend virtual layer to display a default legend in the map.



To customize the legend, with the focus on the map window, in the Layers pane we double-click the Legend virtual layer to launch the Legend dialog.



The Legend dialog opens with default settings.  We can change those and then press Apply to modify the legend.



We change the Text position value to center.   We change the font to a Bold font, and the font size to 9 points, a slightly larger size than the default 8 points.


The preview pane immediately updates to incorporate the changes.  Press Apply to apply the changes to the map without closing the Legend dialog.



The Text element in the legend is the roads : fclass line.  It has been centered, and is rendered using boldfaced font in a slightly larger font size.



We next change the Position of the legend to the left top corner of the map window.   We change the Margin setting to a distance of 20 points for both horizontal and vertical margins.  That moves the legend farther away from the edge of the map window.  We also change the Size of the legend to a width of 120 points, to make the legend narrower.  The Size variable only affects the width, since the vertical height of the legend automatically will be set based on the contents of the legend and the vertical height available in the map window.


We also change the Padding to 10 points, which increases the space between the border of the legend and the contents within.


Press Apply to apply the changes to the legend in the map.



The narrower legend with more space between the borders and the contents looks better.  The larger margin space between the legend and the edge of the map window also makes the legend look less crowded within the map.


However, the text captions in the multiple sample lines for the different colors of road lines look somewhat crowded when aligned to the left.  We can change that.



Settings for text used for multiple sample items, like the roads, are in the Multiple line.  We change the alignment to right.  We also choose an italic font.


Press Apply to see the changes in the map window.



That opens up the legend some more.   Using italic font in a legend is a matter of taste, of course.  


Given the dark background of the map, the white legend background may seem out of place.   If we like, we can change the colors used for text and for background in the legend.



We click on the color wells and change the stroke (foreground) color to white, and the background color to a medium dark gray.   We also change the Stroke value to 2, to make a thicker legend border.


The preview pane shows the effect.   We press Apply to see it in the map.



The result is a legend that stylistically matches the dark background of the map, and which provides a guide to the color meanings of the roads.



Since we have been using the Apply button, the Legend dialog is still open.   Press OK to exit the Legend dialog.


Tech tip:  If we ever want to save the settings used for a legend, that is easy to do.  In the Project pane, right-click onto the map component and choose Properties in the context menu.   



The Properties dialog will have a Legend entry with a text string in human-readable JSON format that contains the style information that customizes the legend.  Copy that text, and Paste it into a Comment or text file.

Example: Customize a Legend in a Map Window

We will repeat the above example for a legend frame in a layout.     We will add the same map used in the prior example to a layout, and then we add a legend frame to the layout using the Create Legend tool.



We zoom into the Layout window to get a better look at the legend.



We see the legend by default starts the same as it did in the map window, using the Legend Mode settings in the Layers pane for the map to guide what layers are shown in the legend, and whether they are shown as short entries or full, multiple rows of entries.


With the focus on the Layout window, in the Info pane we click the [...] browse button to launch the Legend dialog.



The Legend dialog shows default settings for the legend.  



We change all of the settings that are the same as in the Legend dialog for map windows, to the same settings used as before in the map window example.  We do those all at once since we do not have an Apply button, so apply the changes we must press OK to close the dialog, and then press Update Frame in the Info pane to apply the changes to the layout.



The result is a legend that looks very much like the legend we configured in the map window example.   There are two key differences.  The first is that there is no Size control to set the width, but we can do that later in the Info pane. The second difference is that the Position control set to top positions the legend within the legend frame and not within the layout window.   To position the legend within the layout, we can drag it to a different position wherever we want.




To make the legend narrower, we simply drag the edit handle on the side to make the frame narrower.  Note that resizing the frame to be larger than the legend in the vertical dimension has no effect on the legend, while resizing the frame to be smaller in the vertical direction than the legend will result in clipping of some of the legend entries.



To move the legend to a different position, alt-click the legend to pick it (if it is not already picked as shown in the illustration above), and then drag it to the new position.




Style overrides excluded - Legends will capture formatting in the Style pane, but will not capture style overrides used to style objects individually if such have been applied.


More than just maps - Legends can be created for any visual display window that can host multiple layers, such as drawing windows, image windows, or labels windows in addition to map windows. When this documentation refers to a "map window" in the context of creating legends for map windows or for map window frames in layouts, it also intends to refer to all such visual display windows as well.   



See Also



Layers Pane


Info Pane




Layouts: Info Pane


Layouts: Create Commands


Layouts: Legends




Legend Mode


Legends: Tutorial Example - A step by step, illustrated tutorial showing how to create a legend for a map.


Legends: Raster Images - All about creating legends for images (rasters).


Style: Thematic Formatting