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 pl‐
20 colorbar(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, opt_ar‐
30 ray, 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 po‐
69 sition 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 PL_PO‐
78 SITION_BOTTOM bits while the sides are specified by a single
79 value of one of those bits. The adopted coordinates are normal‐
80 ized viewport coordinates if the PL_POSITION_VIEWPORT bit is set
81 or normalized subpage coordinates if the PL_POSITION_SUBPAGE bit
82 is set. Default position bits: If none of PL_POSITION_LEFT,
83 PL_POSITION_RIGHT, PL_POSITION_TOP, or PL_POSITION_BOTTOM are
84 set, then use the combination of PL_POSITION_RIGHT and PL_POSI‐
85 TION_TOP. If neither of PL_POSITION_INSIDE or PL_POSITION_OUT‐
86 SIDE is set, use PL_POSITION_INSIDE. If neither of PL_POSI‐
87 TION_VIEWPORT or PL_POSITION_SUBPAGE is set, use PL_POSI‐
88 TION_VIEWPORT.
89 x (PLFLT(3plplot), 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 in‐
94 ward/outward from the standard corner positions or standard left
95 or right positions if the PL_POSITION_INSIDE/PL_POSITION_OUTSIDE
96 bit is set in position. For the standard top or bottom posi‐
97 tions, 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 in‐
103 ward/outward from the standard corner positions or standard top
104 or bottom positions if the PL_POSITION_INSIDE/PL_POSITION_OUT‐
105 SIDE bit is set in position. For the standard left or right po‐
106 sitions, 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 number of rows in the matrix used to render the nlegend leg‐
127 end entries. For internal transformations of nrow, see further
128 remarks under nlegend.
129 ncolumn (PLINT(3plplot), input)
131 The number of columns in the matrix used to render the nlegend
132 legend entries. For internal transformations of ncolumn, see
133 further remarks under nlegend.
134 nlegend (PLINT(3plplot), input)
136 Number of legend entries. The above nrow and ncolumn values are
137 transformed internally to be consistent with nlegend. If either
138 nrow or ncolumn is non-positive it is replaced by 1. If the re‐
139 sulting product of nrow and ncolumn is less than nlegend, the
140 smaller of the two (or nrow, if nrow == ncolumn) is increased so
141 the product is >= nlegend. Thus, for example, the common nrow =
142 0, ncolumn = 0 case is transformed internally to nrow = nlegend,
143 ncolumn = 1; i.e., the usual case of a legend rendered as a sin‐
144 gle column.
145 opt_array (PLINT_VECTOR(3plplot), input)
147 A vector of nlegend values of options to control each individual
148 plotted area corresponding to a legend entry. If the PL_LEG‐
149 END_NONE bit is set, then nothing is plotted in the plotted
150 area. If the PL_LEGEND_COLOR_BOX, PL_LEGEND_LINE, and/or
151 PL_LEGEND_SYMBOL bits are set, the area corresponding to a leg‐
152 end entry is plotted with a colored box; a line; and/or a line
153 of symbols.
154 text_offset (PLFLT(3plplot), input)
156 Offset of the text area from the plot area in units of character
157 width.
158 text_scale (PLFLT(3plplot), input)
160 Character height scale for text annotations.
161 text_spacing (PLFLT(3plplot), input)
163 Vertical spacing in units of the character height from one leg‐
164 end entry to the next.
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.org/credits.php)
226 have contributed to PLplot over its long history.
227
229 PLplot documentation at http://plplot.org/documentation.php.
230 January, 2023 PLLEGEND(3plplot)