1PLLEGEND(3plplot)                 PLplot API                 PLLEGEND(3plplot)
2
3
4

NAME

6       pllegend  - Plot legend using discretely annotated filled boxes, lines,
7       and/or lines of symbols
8

SYNOPSIS

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

DESCRIPTION

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
28       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
35       This function is used in examples 4, 26, and 33.
36

ARGUMENTS

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
45       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
51       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
64       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
90       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
99       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
108       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
113       bg_color (PLINT(3plplot), input)
114              The cmap0 color  of  the  background  for  the  legend  (PL_LEG‐
115              END_BACKGROUND).
116
117       bb_color (PLINT(3plplot), input)
118              The cmap0 color of the bounding-box line for the legend (PL_LEG‐
119              END_BOUNDING_BOX).
120
121       bb_style (PLINT(3plplot), input)
122              The pllsty style number for the bounding-box line for the legend
123              (PL_LEGEND_BACKGROUND).
124
125       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
130       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
135       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
146       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
155       text_offset (PLFLT(3plplot), input)
156              Offset of the text area from the plot area in units of character
157              width.
158
159       text_scale (PLFLT(3plplot), input)
160              Character height scale for text annotations.
161
162       text_spacing (PLFLT(3plplot), input)
163              Vertical spacing in units of the character height from one  leg‐
164              end entry to the next.
165
166       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
173       text_colors (PLINT_VECTOR(3plplot), input)
174              A vector containing nlegend cmap0 text colors.
175
176       text (PLCHAR_MATRIX(3plplot), input)
177              A  vector of nlegend UTF-8 character strings containing the leg‐
178              end annotations.
179
180       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
184       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
188       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
193       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
197       line_colors (PLINT_VECTOR(3plplot), input)
198              A vector containing nlegend cmap0 line colors (PL_LEGEND_LINE).
199
200       line_styles (PLINT_VECTOR(3plplot), input)
201              A vector containing nlegend line styles (plsty indices) (PL_LEG‐
202              END_LINE).
203
204       line_widths (PLFLT_VECTOR(3plplot), input)
205              A vector containing nlegend line widths (PL_LEGEND_LINE).
206
207       symbol_colors (PLINT_VECTOR(3plplot), input)
208              A vector containing nlegend cmap0 symbol colors  (PL_LEGEND_SYM‐
209              BOL).
210
211       symbol_scales (PLFLT_VECTOR(3plplot), input)
212              A  vector  containing nlegend scale values for the symbol height
213              (PL_LEGEND_SYMBOL).
214
215       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
219       symbols (PLCHAR_MATRIX(3plplot), input)
220              A  vector of nlegend UTF-8 character strings containing the leg‐
221              end symbols. (PL_LEGEND_SYMBOL).
222
223

AUTHORS

225       Many developers (who  are  credited  at  http://plplot.org/credits.php)
226       have contributed to PLplot over its long history.
227

SEE ALSO

229       PLplot documentation at http://plplot.org/documentation.php.
230
231
232
233                                 January, 2023               PLLEGEND(3plplot)
Impressum