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.