GNU Info

(gnuplot.info)key

---

Next: label Prev: isosamples Up: set-show

---

Enter node , (file) or (file)node

 The `set key` enables a key (or legend) describing plots on a plot.

 The contents of the key, i.e., the names given to each plotted data set and
 function and samples of the lines and/or symbols used to represent them, are
 determined by the `title` (Note: title ) and  `with` (Note: with ) options
 of the {s}s`}`plot` (Note: plot ) command. Please see `plot title` and `plot
 with` for more information.

 Syntax:
       set key {  left | right | top | bottom | outside | below
                | <position>}
               {Left | Right} {{no}reverse}
               {samplen <sample_length>} {spacing <vertical_spacing>}
               {width <width_increment>}
               {title "<text>"}
               {{no}box { {linestyle | ls <line_style>}
                          | {linetype | lt <line_type>}
                            {linewidth | lw <line_width>}}}
       set nokey
       show key

 By default the key is placed in the upper right corner of the graph.  The
 keywords `left`, `right`, `top`, `bottom`, `outside` and `below` may be used
 to place the key in the other corners inside the graph or to the right
 (outside) or below the graph.  They may be given alone or combined.

 Justification of the labels within the key is controlled by `Left` or `Right`
 (default is `Right`).  The text and sample can be reversed (`reverse`) and a
 box can be drawn around the key (`box {...}`) in a specified `linetype`
 and `linewidth` (Note: linewidth ), or a user-defined  `linestyle`
 (Note: linestyle ). Note that not all terminal drivers support linewidth
 selection, though.

 The length of the sample line can be controlled by `samplen`.  The sample
 length is computed as the sum of the tic length and <sample_length> times the
 character width.  `samplen` also affects the positions of point samples in
 the key since these are drawn at the midpoint of the sample line, even if it
 is not drawn.  <sample_length> must be an integer.

 The vertical spacing between lines is controlled by `spacing`.  The spacing
 is set equal to the product of the pointsize, the vertical tic size, and
 <vertical_spacing>.  The program will guarantee that the vertical spacing is
 no smaller than the character height.

 The <width_increment> is a number of character widths to be added to or
 subtracted from the length of the string.  This is useful only when you are
 putting a box around the key and you are using control characters in the text.
 `gnuplot` (Note: gnuplot ) simply counts the number of characters in the
 string when computing the box width; this allows you to correct it.

 A title can be put on the key (`title "<text>"`)---see also `syntax`
 (Note: Syntax ) for the distinction between text in single- or
 double-quotes.  The key title uses the same justification as do the plot
 titles.

 The defaults for `set key` are `right`, `top`, `Right`, `noreverse`, `samplen
 4`, `spacing 1.25`, `title ""`, and `nobox`.  The default <linetype> is the
 same as that used for the plot borders.  Entering `set key` with no options
 returns the key to its default configuration.

 The <position> can be a simple x,y,z as in previous versions, but these can
 be preceded by one of four keywords (`first`, `second`, `graph`, `screen`)
 which selects the coordinate system in which the position is specified.  See
 `coordinates` (Note: Coordinates ) for more details.

 The key is drawn as a sequence of lines, with one plot described on each
 line.  On the right-hand side (or the left-hand side, if `reverse` is
 selected) of each line is a representation that attempts to mimic the way the
 curve is plotted.  On the other side of each line is the text description
 (the line title), obtained from the `plot` command.  The lines are vertically
 arranged so that an imaginary straight line divides the left- and right-hand
 sides of the key.  It is the coordinates of the top of this line that are
 specified with the `set key` command.  In a `plot`, only the x and y
 coordinates are used to specify the line position.  For a `splot`
 (Note: splot ), x, y and z are all used as a 3-d location mapped using the
 same mapping as the graph itself to form the required 2-d screen position of
 the imaginary line.

 Some or all of the key may be outside of the graph boundary, although this
 may interfere with other labels and may cause an error on some devices.  If
 you use the keywords `outside` or `below`, `gnuplot` makes space for the keys
 and the graph becomes smaller.  Putting keys outside to the right, they
 occupy as few columns as possible, and putting them below, as many columns as
 possible (depending of the length of the labels), thus stealing as little
 space from the graph as possible.

 When using the TeX or PostScript drivers, or similar drivers where formatting
 information is embedded in the string, `gnuplot` is unable to calculate
 correctly the width of the string for key positioning.  If the key is to be
 positioned at the left, it may be convenient to use the combination  `set key
 left Left reverse`.  The box and gap in the grid will be the width of the
 literal string.

 If `splot` is being used to draw contours, the contour labels will be listed
 in the key.  If the alignment of these labels is poor or a different number
 of decimal places is desired, the label format can be specified.  See `set
 clabel` for details.

 Examples:

 This places the key at the default location:
       set key

 This disables the key:
       set nokey

 This places a key at coordinates 2,3.5,2 in the default (first) coordinate
 system:
       set key 2,3.5,2

 This places the key below the graph:
       set key below

 This places the key in the bottom left corner, left-justifies the text,
 gives it a title, and draws a box around it in linetype 3:
       set key left bottom Left title 'Legend' box 3