1PLLEGEND(3plplot) PLplot API PLLEGEND(3plplot)
2
6 pllegend - Plot legend using discretely annotated filled boxes, lines,
7 and/or lines of symbols
8
10 pllegend(p_legend_width, p_legend_height, opt, position, x, y,
11 plot_width, bg_color, bb_color, bb_style, nrow, ncolumn, nlegend,
12 opt_array, text_offset, text_scale, text_spacing, test_justification,
13 text_colors, text, box_colors, box_patterns, box_scales,
14 box_line_widths, line_colors, line_styles, line_widths, symbol_colors,
15 symbol_scales, symbol_numbers, symbols)
16
18 Routine for creating a discrete plot legend with a plotted filled box,
19 line, and/or line of symbols for each annotated legend entry. (See
20 plcolorbar(3plplot) for similar functionality for creating continuous
21 color bars.) The arguments of pllegend provide control over the loca‐
22 tion and size of the legend as well as the location and characteristics
23 of the elements (most of which are optional) within that legend. The
24 resulting legend is clipped at the boundaries of the current subpage.
25 (N.B. the adopted coordinate system used for some of the parameters is
26 defined in the documentation of the position parameter.)
27 Redacted form: pllegend(p_legend_width, p_legend_height, opt, position,
29 x, y, plot_width, bg_color, bb_color, bb_style, nrow, ncolumn,
30 opt_array, text_offset, text_scale, text_spacing, test_justification,
31 text_colors, text, box_colors, box_patterns, box_scales,
32 box_line_widths, line_colors, line_styles, line_widths, symbol_colors,
33 symbol_scales, symbol_numbers, symbols)
34 This function is used in examples 4, 26, and 33.
36
38 p_legend_width (PLFLT_NC_SCALAR(3plplot), output)
39 Returned value of the legend width in adopted coordinates. This
40 quantity is calculated from plot_width, text_offset, ncolumn
41 (possibly modified inside the routine depending on nlegend and
42 nrow), and the length (calculated internally) of the longest
43 text string.
44 p_legend_height (PLFLT_NC_SCALAR(3plplot), output)
46 Returned value of the legend height in adopted coordinates. This
47 quantity is calculated from text_scale, text_spacing, and nrow
48 (possibly modified inside the routine depending on nlegend and
49 nrow).
50 opt (PLINT(3plplot), input)
52 opt contains bits controlling the overall legend. If the PL_LEG‐
53 END_TEXT_LEFT bit is set, put the text area on the left of the
54 legend and the plotted area on the right. Otherwise, put the
55 text area on the right of the legend and the plotted area on the
56 left. If the PL_LEGEND_BACKGROUND bit is set, plot a (semitrans‐
57 parent) background for the legend. If the PL_LEGEND_BOUNDING_BOX
58 bit is set, plot a bounding box for the legend. If the PL_LEG‐
59 END_ROW_MAJOR bit is set and (both of the possibly internally
60 transformed) nrow > 1 and ncolumn > 1, then plot the resulting
61 array of legend entries in row-major order. Otherwise, plot the
62 legend entries in column-major order.
63 position (PLINT(3plplot), input)
65 position contains bits which control the overall position of the
66 legend and the definition of the adopted coordinates used for
67 positions just like what is done for the position argument for
68 plcolorbar(3plplot). However, note that the defaults for the
69 position bits (see below) are different than the plcolor‐
70 bar(3plplot) case. The combination of the PL_POSITION_LEFT,
71 PL_POSITION_RIGHT, PL_POSITION_TOP, PL_POSITION_BOTTOM, PL_POSI‐
72 TION_INSIDE, and PL_POSITION_OUTSIDE bits specifies one of the
73 16 possible standard positions (the 4 corners and centers of the
74 4 sides for both the inside and outside cases) of the legend
75 relative to the adopted coordinate system. The corner positions
76 are specified by the appropriate combination of two of the
77 PL_POSITION_LEFT, PL_POSITION_RIGHT, PL_POSITION_TOP, and
78 PL_POSITION_BOTTOM bits while the sides are specified by a sin‐
79 gle value of one of those bits. The adopted coordinates are
80 normalized viewport coordinates if the PL_POSITION_VIEWPORT bit
81 is set or normalized subpage coordinates if the PL_POSITION_SUB‐
82 PAGE bit is set. Default position bits: If none of PL_POSI‐
83 TION_LEFT, PL_POSITION_RIGHT, PL_POSITION_TOP, or PL_POSI‐
84 TION_BOTTOM are set, then use the combination of PL_POSI‐
85 TION_RIGHT and PL_POSITION_TOP. If neither of PL_POSITION_INSIDE
86 or PL_POSITION_OUTSIDE is set, use PL_POSITION_INSIDE. If nei‐
87 ther of PL_POSITION_VIEWPORT or PL_POSITION_SUBPAGE is set, use
88 PL_POSITION_VIEWPORT.
89 x (PLFLT, input)
91 X offset of the legend position in adopted coordinates from the
92 specified standard position of the legend. For positive x, the
93 direction of motion away from the standard position is
94 inward/outward from the standard corner positions or standard
95 left or right positions if the PL_POSITION_INSIDE/PL_POSI‐
96 TION_OUTSIDE bit is set in position. For the standard top or
97 bottom positions, the direction of motion is toward positive X.
98 y (PLFLT(3plplot), input)
100 Y offset of the legend position in adopted coordinates from the
101 specified standard position of the legend. For positive y, the
102 direction of motion away from the standard position is
103 inward/outward from the standard corner positions or standard
104 top or bottom positions if the PL_POSITION_INSIDE/PL_POSI‐
105 TION_OUTSIDE bit is set in position. For the standard left or
106 right positions, the direction of motion is toward positive Y.
107 plot_width (PLFLT(3plplot), input)
109 Horizontal width in adopted coordinates of the plot area (where
110 the colored boxes, lines, and/or lines of symbols are drawn) of
111 the legend.
112 bg_color (PLINT(3plplot), input)
114 The cmap0 color of the background for the legend (PL_LEG‐
115 END_BACKGROUND).
116 bb_color (PLINT(3plplot), input)
118 The cmap0 color of the bounding-box line for the legend (PL_LEG‐
119 END_BOUNDING_BOX).
120 bb_style (PLINT(3plplot), input)
122 The pllsty style number for the bounding-box line for the legend
123 (PL_LEGEND_BACKGROUND).
124 nrow (PLINT(3plplot), input)
126 The cmap0 index of the background color for the legend (PL_LEG‐
127 END_BACKGROUND).
128 ncolumn (PLINT(3plplot), input)
130 The cmap0 index of the background color for the legend (PL_LEG‐
131 END_BACKGROUND).
132 nlegend (PLINT(3plplot), input)
134 Number of legend entries. N.B. The total vertical height of
135 the legend in adopted coordinates is calculated internally from
136 nlegend, text_scale (see below), and text_spacing (see below).
137 opt_array (PLINT_VECTOR(3plplot), input)
139 A vector of nlegend values of options to control each individual
140 plotted area corresponding to a legend entry. If the PL_LEG‐
141 END_NONE bit is set, then nothing is plotted in the plotted
142 area. If the PL_LEGEND_COLOR_BOX, PL_LEGEND_LINE, and/or
143 PL_LEGEND_SYMBOL bits are set, the area corresponding to a leg‐
144 end entry is plotted with a colored box; a line; and/or a line
145 of symbols.
146 text_offset (PLFLT(3plplot), input)
148 Offset of the text area from the plot area in units of character
149 width. N.B. The total horizontal width of the legend in
150 adopted coordinates is calculated internally from plot_width
151 (see above), text_offset, and length (calculated internally) of
152 the longest text string.
153 text_scale (PLFLT(3plplot), input)
155 Character height scale for text annotations. N.B. The total
156 vertical height of the legend in adopted coordinates is calcu‐
157 lated internally from nlegend (see above), text_scale, and
158 text_spacing (see below).
159 text_spacing (PLFLT(3plplot), input)
161 Vertical spacing in units of the character height from one leg‐
162 end entry to the next. N.B. The total vertical height of the
163 legend in adopted coordinates is calculated internally from nle‐
164 gend (see above), text_scale (see above), and text_spacing.
165 text_justification (PLFLT(3plplot), input)
167 Justification parameter used for text justification. The most
168 common values of text_justification are 0., 0.5, or 1. corre‐
169 sponding to a text that is left justified, centred, or right
170 justified within the text area, but other values are allowed as
171 well.
172 text_colors (PLINT_VECTOR(3plplot), input)
174 A vector containing nlegend cmap0 text colors.
175 text (PLCHAR_MATRIX(3plplot), input)
177 A vector of nlegend UTF-8 character strings containing the leg‐
178 end annotations.
179 box_colors (PLINT_VECTOR(3plplot), input)
181 A vector containing nlegend cmap0 colors for the discrete col‐
182 ored boxes (PL_LEGEND_COLOR_BOX).
183 box_patterns (PLINT_VECTOR(3plplot), input)
185 A vector containing nlegend patterns (plpsty indices) for the
186 discrete colored boxes (PL_LEGEND_COLOR_BOX).
187 box_scales (PLFLT_VECTOR(3plplot), input)
189 A vector containing nlegend scales (units of fraction of charac‐
190 ter height) for the height of the discrete colored boxes
191 (PL_LEGEND_COLOR_BOX).
192 box_line_widths (PLFLT_VECTOR(3plplot), input)
194 A vector containing nlegend line widths for the patterns speci‐
195 fied by box_patterns (PL_LEGEND_COLOR_BOX).
196 line_colors (PLINT_VECTOR(3plplot), input)
198 A vector containing nlegend cmap0 line colors (PL_LEGEND_LINE).
199 line_styles (PLINT_VECTOR(3plplot), input)
201 A vector containing nlegend line styles (plsty indices) (PL_LEG‐
202 END_LINE).
203 line_widths (PLFLT_VECTOR(3plplot), input)
205 A vector containing nlegend line widths (PL_LEGEND_LINE).
206 symbol_colors (PLINT_VECTOR(3plplot), input)
208 A vector containing nlegend cmap0 symbol colors (PL_LEGEND_SYM‐
209 BOL).
210 symbol_scales (PLFLT_VECTOR(3plplot), input)
212 A vector containing nlegend scale values for the symbol height
213 (PL_LEGEND_SYMBOL).
214 symbol_numbers (PLINT_VECTOR(3plplot), input)
216 A vector containing nlegend numbers of symbols to be drawn
217 across the width of the plotted area (PL_LEGEND_SYMBOL).
218 symbols (PLCHAR_MATRIX(3plplot), input)
220 A vector of nlegend UTF-8 character strings containing the leg‐
221 end symbols. (PL_LEGEND_SYMBOL).
222
225 Many developers (who are credited at http://plplot.source‐
226 forge.net/credits.php) have contributed to PLplot over its long his‐
227 tory.
228
230 PLplot documentation at http://plplot.sourceforge.net/documenta‐
231 tion.php.
232 August, 2017 PLLEGEND(3plplot)