#### 15.3.3.4 Legend Properties ¶

Properties of `legend` objects (see legend):

#### Categories: ¶

Callback Execution | Layout | Legend Appearance | Object Identification | Object Position | Text Appearance

#### Callback Execution ¶

`itemhitfcn`: def. `[](0x0)` ¶

  Callback function which is executed when a legend item is clicked. See Callbacks section.

  The callback function must have the following prototype `fcn (hlegend, evnt)`, where `hlegend` is the legend object handle and `evnt` is a structure with the following fields:

  `Peer`

    Handle of the plot object to which the clicked item is associated.

  `Region`

    May be `"icon"` or `"label"` depending on which part of the item is clicked.

  `SelectionType`

    One of `"normal"`, `"extend"`, `"open"`, or `"alt"`. See Figure `"selectiontype"`.

  `Source`

    Handle of the legend object.

  `EventName`

    Name is `"ItemHit"`.

#### Layout ¶

`autoupdate`: `"off"` | {`"on"`} ¶

  Control whether the number of legend items is updated automatically when objects are added to (or deleted from) the peer axes. For example:

      ## Create a single plot with its legend.
      figure ();
      plot (1:10);
      legend ("Slope 1");
      ## Add another plot and specify its displayname so that
      ## the legend is correctly updated.
      hold on;
      plot ((1:10) * 2, "displayname", "Slope 2");
      ## Stop automatic updates for further plots.
      legend ("autoupdate", "off");
      plot ((1:10) * 3);

`numcolumns`: scalar integer, def. `1` ¶

  Control the number of columns used in the layout of the legend items. For example:

      figure ();
      plot (rand (30));
      legend ("numcolumns", 3);

  Setting `numcolumns` also forces the `numcolumnsmode` property to be set to `"manual"`.

`orientation`: `"horizontal"` | {`"vertical"`} ¶

  Control whether the legend items are arranged vertically (column-wise) or horizontally (row-wise).

#### Legend Appearance ¶

`box`: `"off"` | {`"on"`} ¶

  Control whether the legend has a surrounding box.

`color`: colorspec, def. `[1 1 1]` ¶

  Color of the legend background. See colorspec.

`edgecolor`: colorspec, def. `[0.1500 0.1500 0.1500]` ¶

  Control the color of the legend outline.

#### Object Identification ¶

`title`: graphics handle ¶

  Graphics handle of the title text object.

#### Object Position ¶

`location`: `"best"` | `"bestoutside"` | `"east"` | `"eastoutside"` | `"none"` | `"north"` | {`"northeast"`} | `"northeastoutside"` | `"northoutside"` | `"northwest"` | `"northwestoutside"` | `"south"` | `"southeast"` | `"southeastoutside"` | `"southoutside"` | `"southwest"` | `"southwestoutside"` | `"west"` | `"westoutside"` ¶

  Control the location of the legend.

`position`: four-element vector ¶

  Specify the position of the legend excluding its title. The four elements of the vector are the coordinates of the lower left corner and width and height of the legend. Changing this property also switches the `"location"` to `"none"`.

`units`: `"centimeters"` | `"characters"` | `"inches"` | {`"normalized"`} | `"pixels"` | `"points"` ¶

  Units used to interpret the `"position"` property.

#### Text Appearance ¶

`fontangle`: `"italic"` | {`"normal"`} ¶

  Control whether the font is italic or normal.

`fontname`: string, def. `"*"` ¶

  Name of font used for text rendering. When setting this property, the text rendering engine will search for a matching font in your system. If none is found then text is rendered using a default sans serif font (same as the default `"*"` value).

  Programming Note: On systems that don’t use FontConfig natively (all but Linux), the font cache is built when Octave is installed. You will need to run `system ("fc-cache -fv")` manually after installing new fonts.

`fontsize`: scalar, def. `9` ¶

  Size of the font used for text rendering. See fontunits property. Setting `fontsize` also forces the `fontsizemode` property to be set to `"manual"`.

`fontunits`: `"centimeters"` | `"inches"` | `"normalized"` | `"pixels"` | {`"points"`} ¶

  Units used to interpret the `"fontsize"` property.

`fontweight`: `"bold"` | {`"normal"`} ¶

  Control the variant of the base font used for text rendering.

`string`: string | cell array of strings ¶

  List of labels for the legend items. For example:

      figure ();
      plot (rand (20));
      ## Let legend choose names automatically
      hl = legend ();
      ## Selectively change some names
      str = get (hl, "string");
      str(1:5:end) = "Garbage";
      set (hl, "string", str);

`textcolor`: colorspec, def. `[0 0 0]` ¶

  Control the color of the text strings for legend items.