# line

## Purpose

Create line object.

## Synopsis

    line(x,y)
    line(x,y,z)
    line('PropertyName',PropertyValue...)
    line(...)

## Description

`line` is the low-level graphics function for creating line objects. Line objects are children of axes objects. They are the fundamental graphics objects used to generate plots, contours and edges of surfaces. The `line` function allows you to specify property name/property value pairs as input arguments. These properties, which control various aspects of the line object, are described under "Object Properties". You can also set and query property values after creating the object using the `set` and `get` functions.

Unlike high-level functions such as `plot`, `line` does not clear the axes, set viewing parameters, or perform any actions other than generating a line object in the current axes. `line` is a low-level function that, ordinarily, is not used directly. Use `plot` and `plot3` instead.

`line(x,y)` adds the line in vectors `x` and `y` to the current axes. If `x` and `y` are matrices of the same size, `line` draws one line per column.

`line(x,y,z)` creates lines in three-dimensional coordinates.

The `x`, `y` pair (`x`, `y`, `z` triple for three-dimensional) can be followed by property name/property value pairs to specify additional line properties. You can omit the `x`, `y`, pair (`x`, `y`, `z` triple) entirely and specify all properties using property name/property value pairs. For example, the following statements are equivalent:

    line('XData',x,'YData',y,'ZData',z)
    line(x,y,z)

`line('PropertyName',PropertyValue...)` specifies property name/property value pairs as input arguments.

`h = line(...)` returns a column vector of handles corresponding to each line object the function creates.Object Properties

This section lists property names along with the type of values each accepts.

`ButtonDownFcn`
  Callback string, object selection.

  Any legal MATLAB expression, including the name of an M-file or function. When you select the object, the string is passed to the `eval` function to execute the specified function. Initially the empty matrix.

`Children`
  Children of line.

  Always the empty matrix; line objects have no children.

`Clipping`
  Clipping mode.

  `on` (Default.) Any portion of the line outside the axes rectangle is not displayed.
  `off` Line data is not clipped.

`Color`
  Line color.

  A three-element RGB vector or one of MATLAB's predefined names, specifying the line color. See the ``ColorSpec reference page for more information on specifying color.

`EraseMode`
  Erase mode.

  This property controls the technique MATLAB uses to draw and erase line objects. This property is useful in creating animated sequences, where control of individual object redraw is necessary to improve performance and obtain the desired effect.
  `normal` (Default.) Redraws the affected region of the display, performing the three-dimensional analysis necessary to ensure that all objects are rendered correctly. This mode produces the most accurate picture, but is the slowest. The other modes are faster, but do not perform a complete redraw and are therefore less accurate.
  `none` The line is not erased when it is moved or destroyed.
  `xor` The line is drawn and erased by performing an exclusive OR (XOR) with the color of the screen beneath it. When the line is erased, it does not damage the objects beneath it. Lines are dependent on the color of the screen beneath them, however, and are correctly colored only when over the figure background color.
  `background` The line is erased by drawing it in the figure's background color. This damages objects that are behind the erased line, but lines are always properly colored.

`Interruptible`
  Callback interruptibility.

  `yes` The callback specified by `ButtonDownFcn` is interruptible by other callbacks.
  `no` (Default.) The `ButtonDownFcn` callback is not interruptible.

`LineStyle`
  Line style.

  This property determines the type of line drawn. Specify a linestyle to be plotted through the data points or a scalable marker type to be placed only at data points:
  - Line styles: solid (`-`), dashed (`-` `-`), dotted (`:`), dashdot (`-.`).
  - Marker types: circle (`o`), plus (`+`), point (`.`), star (*), x-mark (`x`).
  The default line style is a solid line.

`LineWidth`
  Line width.

  The width, in points, of the line object. The default line width is 0.5.

`MarkerSize`
  Marker scale factor.

  A scalar specifying the scale factor, in points, for line markers. This applies only to the marker types circle, plus, point, star, and x-mark. The default marker size is 6 points.

`Parent`
  Handle of the line's parent object.

  A read-only property that contains the handle of the line's parent object. The parent of a line object is the axes in which it is displayed.

`Type`
  Type of graphics object.

  A read-only string; always `'line'` for a line object.

`UserData`
  User-specified data.

  Any matrix you want to associate with the line object. The object does not use this data, but you can retrieve it using the `get` command`.`

`Visible`
  Line visibility.

  `on` (Default.) Line is visible on the screen.
  `off` Line is not visible on the screen.

`XData`
  Line x-coordinates.

  A vector of x-coordinates for the line. If a matrix, each column is a separate line, and all data (`YData` and `ZData`) must have the same number of rows. `line` replicates a single column to match the number of columns in other data properties (see "Examples").

`YData`
  Line y-coordinates.

  A vector of y-coordinates for the line. If a matrix, each column is a separate line, and all data (`XData` and `ZData`) must have the same number of rows. `line` replicates a single column to match the number of columns in other data properties (see "Examples").

`ZData`
  Line z-coordinates.

  A vector of z-coordinates for the line. If a matrix, each column is a separate line, and all data (`XData` and `YData`) must have the same number of rows. `line` replicates a single column to match the number of columns in other data properties (see "Examples").

## Examples

This statement re-uses the one column of data specified for `ZData` to produce two lines, each having four points.

    line(rand(4,2),rand(4,2),rand(4,1))

If all the data has the same number of columns and one row each, MATLAB transposes the matrices to produce data for plotting. For example,

    line(rand(1,4),rand(1,4),rand(1,4))

is changed to

    line(rand(4,1),rand(4,1),rand(4,1))

This also applies to the case when just one or two matrices have one column. For example, the statement

    line(rand(2,4),rand(2,4),rand(1,4))

is equivalent to,

    line(rand(4,2),rand(4,2),rand(4,1))

## See Also

    patch, plot, plot3, text

(c) Copyright 1994 by The MathWorks, Inc.