\function{grace_new}
\synopsis{Creata a new grace plotting instance}
\usage{Struct_Type grace_new ( [args] )}
\description
 This function creates a new instance of a grace plotting object.
 When called with no arguments, it starts up \exmp{xmgrace} using the
 \exmp{-nosafe} command-line argument.  If a different set of
 arguments are desired, then those may be specified as an array of
 strings.  For example, to start Grace via \exmp{xmgrace -fixed -nosafe}, use
#v+
     g = grace_new (["xmgrace", "-fixed", "-nosafe"]);
#v-
 Note that the name of the application to run (\exmp{xmgrace} in this
 case) must be the first element in the array.  If the \exmp{DISPLAY}
 environment variable is not set, the \exmp{gracebat} application will
 be started instead.

\seealso{grace.plot, grace.close, grace.save}
\done

\function{grace.plot}
\synopsis{Plot points or lines}
\usage{.plot (x [,y [,dy]] [;qualifiers])}
\description
 The \exmp{plot} method erases the currently active plot and then
 plots the specified points.  If called with a single argument, that
 argument will be used as the \exmp{y} points, and \exmp{[1,2,...]}
 will be used as the x points.  If called with 3 arguments, the third
 argument will be used as an error bar.
\qualifiers
#v+
   logx[=0|1]            Turn on/off log scaling for the x axis
   logy[=0|1]            Turn on/off log scaling for the y axis
   line=int              Linestyle (0 = no line)
   color=int|str         Line color
   width=float           Line width 
   fill=int
   fillcolor=int         Color for the fill region
   fillpat=int           Pattern index for filling
   sym=int               Plot symbol (0 = none)
   symcolor=int|str      Symbol color
   symsize=float         Symbol size (float)
   symfillcolor=int|str  Color used to fill symbols
   symfill=int
   grid[=0|1|2|3]        Draw grid: 0:none, 1:major, 2:minor, 3:major+minor
   dropline              Draw a dropline for each point
   graphtype=str         One of "xy", "xydx", "xydy", "xydxdy", etc..
#v-
 The following qualifiers control various attributes of the errorbars:
#v+
   errorbar_place=str
   errorbar_color=int|str
   errorbar_pattern=int
   errorbar_linestyle=int
   errorbar_linewidth=float
   errorbar_riser_linewidth=float
   errorbar_riser_linestyle=int
   errorbar_riser_clip_length=float
#v-
 Note: Using a negative value for \exmp{sym} is equivalent to setting
 \exmp{line=0} and \exmp{sym=abs(sym)}.
\example
#v+
   x = [-10:10:#50];
   y = sin(x);
   g = grace_new ();
   g.plot (x, y ; sym=-4, symfill=2);
#v-
\notes
 Use the \exmp{.get_colors} method to see what colors are available.
\seealso{grace_new, grace.oplot, grace.hplot, grace.multi, grace.tick}
\done

\function{grace.focus}
\synopsis{Set the focus to a specified plot}
\usage{grace.focus ( [ [nth] | [nrow,ncol] ] )}}
\description
 This method is used to change the focus of the plotting commands
 to a specified graph in a multi-plot situation.  When called without
 arguments, the focus will be changed to the next graph.  When called
 with the single argument \exmp{nth}, the focus will be set to the
 \exmp{nth} plot (\exmp{nth=1,2,..}).  When called with 2 arguments,
 the first argument specifies the row and the second argument specfies
 the column (\exmp{row,col = 1,2,..}).
\example
#v+
   g = grace_new ();
   g.multi (2, 1; sizes=[3,1]);
   g.focus (1,1);
   g.plot (x,y);
   g.focus (2,1);
   g.plot (x,sin(x*y));
#v-
\seealso{grace.multi}
\done

\function{grace.oplot}
\synopsis{Overplot points or lines}
\usage{.oplot (x [,y [,dy]] [;qualifiers])}
\description
 The \exmp{oplot} method may be used to add additional points or lines
 to a plot.  It behaves like \exmp{plot} except that it does not erase
 the current plot.  See the \exmp{plot} method documentation for
 more details.
\seealso{grace.plot, grace.clear}
\done

\function{grace.tick}
\synopsis{Control the axis tick marks}
\usage{.tick ([enable_major [,enable_minor]] [;qualifiers])}
\description
 This method may be used to control various aspects of the ticks
 marks.  If called with one argument, the major tics may be turned on
 or off according to whether the argument is non-zero or not.  A
 non-zero value turns on the generation of major ticks, and a value of
 zero turns off their generation.  The optional second parameter
 controls the generation of minor ticks in a similar manner.  Most
 other attributes are controlled by qualifiers.
\qualifiers
#v+
  offsetx=int      offset the axis in the x direction by val
  offsety=int      offset the axis in the y direction by val
  majorstyle=int   linestyle for major ticks
  majorwidth=int   line width for major ticks
  majorsize=int    size of the major ticks
  majorcolor=val   color of the major ticks
  minorstyle=int   linestyle for minor ticks
  minorwidth=int   line width for minor ticks
  minorsize=int    size of the minor ticks
  minorcolor=val   color of the minor ticks
  majorgrid=0|1    enable(1) or disable the major grid
  minorgrid=0|1    enable(1) or disable the minor grid
#v-
\example
#v+
  g = grace_new ();
  g.tick(;minorstyle=2);
  g.plot(x,y;grid=3);
#v-
\notes
 The tick method operates on both the x and y axes.  Use the
 \exmp{xtick} and \exmp{ytick} methods for control over the
 corresponding axes.
 
 The linestyle, width, and color of the major and minor grid lines are
 controlled by the corresponding tick attributes.
\seealso{grace.xtick, grace.ytick, grace.plot}
\done

\function{grace.label}
\synopsis{Add a text label to a graph}
\usage{.label (string, x, y [;qualifiers])}
\description
 This method may be used to add a text label to the current graph at
 the specfied world coordinate.
\qualifiers
#v+
   viewport    Use viewport coordinates instead of world coordinates
   world       Use world coordinates (default)
   rot=angle   Rotate the text by the specified angle
   font=int    Use the specified font
   just=int    justification: left=0, right=1, 2=center
   size=float  Character size to use (default=1)
#v-
\notes
 It is not a good idea to mix calls to this method with the creation
 of new text strings via the GUI.  As Grace does not permit an
 external program to delete individual strings, the grace module keeps
 an internal table of string ids that have been used.  New strings
 created via the GUI invalidate the table, and there is no way for the
 module to know that this has happened.
\seealso{grace.xlabel, grace.title, grace.ylabel}
\done

\function{grace.save}
\synopsis{Save the plot to a file}
\usage{.save(filename [;device])}
\description
 This method saves the plot to the specified filename.  Normally
 the file format is determined from the filename extension, e.g.,
 \exmp{foo.ps} indicates that \exmp{postscript} format is to be used.
 This \exmp{device} qualifier may be used to explicitely specify the
 format.
\example
#v+
    g.save ("foo.eps");            % Encapsulated Postscript
    g.save ("foo.agr");            % Grace format
    g.save ("foo.out"; device=png);
#v-
\seealso{grace.close}
\done

\function{grace.new_color}
\synopsis{Add a color to the colormap}
\usage{.new_color (name, rgb)}
\description
 The \exmp{new_color} method may be used to define a new color name,
 or redefine an existing color.  The \exmp{rgb} parameter must be an
 integer that encodes the RGB value to be associated with the name.
 The \exmp{id} qualifier may be used to map the color to a specific
 color id value.
\example
#v+
   g.new_color ("royalblue", 0x4169E1);
   g.new_color ("royalblue", (65 shl 16)|(105 shl 8)|225);
#v-
 The latter example shows how to construct the rgb-encoded integer
 from decimal rgb values.
\seealso{grace.plot, grace.get_colors}
\done 

\function{grace.get_colors}
\synopsis{Get a list of the color names}
\usage{String_Type[] = .get_colors()}
\description
 This method returns an array of the color names that have been
 defined.
\example
#v+
   slsh> print (g.get_colors());
#v-
\seealso{grace.new_color, grace.plot}
\done

\function{grace.multi}
\synopsis{Arrange graphs into a rectangular grid}
\usage{.multi(nrows,ncols [;qualifiers]}
\description
 This method may be used to layout graphs onto a rectangular grid
 consisting of \exmp{nrows} and \exmp{ncols}.  Qualifiers may be used
 to specify the horizontal and vertical separations of the graphs.
\qualifiers
#v+
   vgap=value     Controls the vertical spacing between graph windows.
   hgap=value     Controls the horizontal spacing between graph windows.
   offset=value   Sets the distance from the page edges.
#v-
 The values for the \exmp{vgap} and \exmp{hgap} qualifiers appear
 to be fractions of the graph viewport size.  The default values are
 \exmp{vgap=0.3} and \exmp{hgap=0.3}.  The value of the \exmp{offset}
 qualifier appears to a fraction of the page size; the default value
 is 0.15.
\seealso{grace.viewport}
\done

\function{grace.viewport}
\synopsis{Set the viewport for the current graph}
\usage{.viewport(xmin,xmax,ymin,ymax)}
\description
 This method may be used to set the viewport for the current graph.
 Each of the values must be expressed as a fraction of the longer
 page-size value.  For example, if the page size is 8.5 by 11 inches,
 in portrait mode, then the X viewport coordinate runs from 0 to
 8.5/11=0.773, and the Y coordinate runs from 0 to 1.  The rationale
 behind this stems from the desire to keep the physical size of the
 viewport an invariant with respect to landscape or portrait mode.
\seealso{grace.pagesize}
\done

\function{grace.pagesize}
\synopsis{Set the page size}
\usage{.pagesize(dx, dy | "letter" | "a4" [;qualifiers])}
\description
 This method may be used to set the size of the plotting page.  The
 value \exmp{dx} and \exmp{dy} are interpreted as 1/72 of an inch by
 some plot devices, and as pixels by others.  Alternatively, a single
 string such "a4" or "letter" may be used to select the corresponding
 page size.
 
 After calling this method it is a good idea to re-adjust the
 viewport.  An easy way to do this is to use the \exmp{.multi} method.
\qualifiers
#v+
    units="cm"|"in"       Interpret dx and dy in the corresponding units
    landscape             Use landscape mode
    portrait              Use portrait mode
#v-
\example
#v+
    g.pagesize (14, 12 ; units="cm");
    g.multi(1,1);
#v-
\seealso{grace.viewport, grace.multi}
\done

\function{grace.hplot}
\synopsis{Plot a histogram}
\usage{.hplot(x, y [,dy1 [,dy2]] [;qualifiers])}
\description
 This method is typically used to to plot binned data.  In this
 context, \exmp{x} is an array that represents the lower bin edges
 and \exmp{y} is an array that gives the value of each bin.  If the
 optional third or fourth arguments are present, the corresponding
 error bars (symmetric or asymmetric) will also be plotted.
\qualifiers
  The \exmp{hplot} method accepts the same set of qualifiers as the
  the \exmp{plot} method.  However, the \exmp{sym} qualifier is
  ignored unless error-bars are drawn, in which case the symbol is
  associated with the error bar.
\example
#v+
   xbins = [1:1024:8];
   h = hist1d (xbins, pnts);
   g.plot (xbins, h, sqrt(h) ; color="red", sym=2);
#v-
\notes
 The array \exmp{x} that specifies the lower bin edges must be in an
 increasing order such that \exmp{x[j+1]>x[j]}.
\seealso{grace.plot, grace.ohplot}
\done

\function{grace.ohplot}
\synopsis{Overplot a histogram}
\usage{.ohplot()}
\description
  This method may be used to add a histogram plot to a graph.  See
  the \exmp{hplot} method for additional information.
\seealso{grace.hplot, grace.oplot}
\done


\function{grace.xrange}
\synopsis{Set the world coordinates for the X axis}
\usage{.xrange(xmin, xmax)}
\description
  This method may be used to assign world coordinate ranges for the
  \exmp{X} axis.  If \exmp{xmin} or \exmp{xmax} is NULL, the
  corresponding limit will be computed from the data.
\example
#v+
   xrange (min(x), max(x));
   xrange (,max(x));          % Set just the upper limit
   xrange (,);                % Turn on autoscaling for this axis
#v-
\seealso{grace.yrange, grace.world}
\done


\function{grace.yrange}
\synopsis{Set the world coordinates for the Y axis}
\usage{.yrange()}
\description
  This method may be used to assign world coordinate ranges for the
  \exmp{Y} axis.  If \exmp{ymin} or \exmp{ymax} is NULL, the
  corresponding limit will be computed from the data.
\example
#v+
   xrange (min(y), max(y));
   xrange (,max(y));          % Set just the upper limit
   xrange (,);                % Turn on autoscaling for this axis
#v-
\seealso{grace.xrange, grace.world}
\done


\function{grace.world}
\synopsis{Set the world coordinates}
\usage{.world( [ xmin,xmax,ymin,ymax ])}
\description
  This method may be used to assign world coordinate ranges for the
  \exmp{X} and \exmp{Y} axes of the current graph.  If any of these
  values is NULL, the corresponding limit will be computed from the
  data (autoscaling).  When called without arguments, all limits will
  be computed from the data.
\seealso{grace.xrange, grace.yrange, grace.viewport}
\done


\function{grace.ylabel}
\synopsis{Add the Y-axis label}
\usage{.ylabel(string)}
\description
  This method may be used to add a label to the Y axis.
\qualifiers
#v+
    color=int|str    Label color
    size=float       Label Size
    font=int         Font id
#v-
\seealso{grace.xlabel, grace.title, grace.label}
\done


\function{grace.xlabel}
\synopsis{Add the X-axis label}
\usage{.xlabel()}
\description
  This method may be used to add a label to the X axis.
\qualifiers
#v+
    color=int|str    Label color
    size=float       Label Size
    font=int         Font id
#v-
\seealso{grace.ylabel, grace.title, grace.label}
\done

\function{grace.title}
\synopsis{Add the title to the graph}
\usage{.title(string)}
\description
  This method may be used to add a title to the top of the current
  graph.
\qualifiers
#v+
    color=int|str    Label color
    size=float       Label Size
    font=int         Font id
#v-
\seealso{grace.xlabel, grace.ylabel, grace.subtitle, grace.label}
\done


\function{grace.subtitle}
\synopsis{Add the subtitle to the graph}
\usage{.subtitle(string)}
\description
  This method may be used to add a subtitle to the top of the current
  graph under the main graph title.
\qualifiers
#v+
    color=int|str    Label color
    size=float       Label Size
    font=int         Font id
#v-
\seealso{grace.xlabel, grace.ylabel, grace.title, grace.label}
\done

\function{grace.redraw}
\synopsis{Redraw the Grace display}
\usage{.redraw()}
\description
  This method is sometimes necessary to tell Grace to redraw or
  refresh display.
\seealso{grace.plot}
\done


\function{grace.clear}
\synopsis{Clear the current graph}
\usage{.clear()}
\description
  This function may be used to clear the current graph.  Is it not
  normally needed since the \exmp{plot} and \exmp{hplot} methods
  automatically do this.
\seealso{grace.kill, grace.close, grace.plot}
\done


\function{grace.close}
\synopsis{Close the grace session}
\usage{.close()}
\description
  This method is used to shutdown the Grace GUI.  Unless this function
  is called, the GUI will remain active even after the \slang
  application has exited.
\seealso{grace_new, grace.save}
\done

\function{grace.kill}
\synopsis{Delete the current graph}
\usage{.kill()}
\description
  This method may be used to delete the current graph.  It can be
  useful in a multi-plot situation when some graphs are not needed.
\seealso{grace.clear, grace.close}
\done

\function{grace.logx}
\synopsis{Change the X axis to a log scale}
\usage{.logx()}
\description
  This method causes the X axis to use log scaling.  If the
  currently focused graph has a world coordinate
  system that conflicts with log scaling, the world coordinates will
  be changed accordingly (restricted to positive values).
\notes
  Normally log scaling is specified when the plot is made via the
  \exmp{plot} method's \exmp{logx} qualifier.
\done

\function{grace.logy}
\synopsis{Change the Y axis to a log scale}
\usage{.logy()}
\description
  This method causes the Y axis to use log scaling.  If the
  currently focused graph has a world coordinate
  system that conflicts with log scaling, the world coordinates will
  be changed accordingly (restricted to positive values).
\notes
  Normally log scaling is specified when the plot is made via the
  \exmp{plot} method's \exmp{logx} qualifier.
\seealso{grace.logx, grace.linx, grace.liny}
\done


\function{grace.linx}
\synopsis{Change the X axis to a linear scale}
\usage{.linx()}
\description
  This method may be used to cause the X axis of the current graph to
  use linear scaling.
\seealso{grace.liny, grace.logx, grace.logy}
\done


\function{grace.liny}
\synopsis{Change the Y axis to a linear scale}
\usage{.liny()}
\description
  This method may be used to cause the Y axis of the current graph to
  use linear scaling.
\seealso{grace.linx, grace.logx, grace.logy}
\done


\function{grace.legend}
\synopsis{Add a legend to the current graph}
\usage{.legend(x, y, names)}
\description
  This method may be used to add a legend to the graph at the
  coordinate (x,y).  The legend is formed from the \exmp{names} array
  and representative lines or symbols used to draw the corresponding
  curves.
\qualifiers
These qualifiers control attribute of the objects in the legend box:
#v+
    font=int            Font id
    size=float          character size (default: 1)
    color=int|str       color
    vgap=int
    hgap=int
    length=int
#v-
The following qualifiers control the legend box itself:
#v+
    loctype=str             "world" or "view"   (default: "world")
    box=0|1                 Turn the box off(0) or on(1)
    box_line=int            Line style
    box_color=int|str       Line color
    box_linewidth=float
    box_pattern=int
    box_fillcolor=int|str
    box_fillpattern=int
#v-
\example
#v+
   g.plot (x,f(x));
   g.oplot (x,g(x));
   g.legend (2.1, 3.9, ["f(x)", "g(x)"]; box=0);
#v-
\seealso{grace.label, grace.title, grace.plot}
\done

\function{grace.xtick}
\synopsis{Adjust the X axis ticks}
\usage{.xtick()}
\description
  This method may be used to control certain attributes of the X axis
  tick marks.  See the documentation for the \exmp{tick} method for
  more information.
\seealso{grace.tick, grace.ytick}
\done

\function{grace.ytick}
\synopsis{Adjust the Y axis ticks}
\usage{.ytick()}
\description
  This method may be used to control certain attributes of the Y axis
  tick marks.  See the documentation for the \exmp{tick} method for
  more information.
\seealso{grace.tick, grace.ytick}
\done

\function{grace.new_color}
\synopsis{Define a new color name}
\usage{.new_color(name, RGB)}
\description
 This method may be used to add a new named color or redefine a named
 color.  The first parameter is a string that specifies the name of
 the color, and the second is a 3 element integer array whose successive
 elements specify the Red, Green, and Blue content of the color.
 0-255. for the color.
\qualifiers
  id=int     Map the named color to the specified color id or index
\example
#v+
   g.new_color("skyblue3", [108, 166, 205]);
   g.plot (x,y; color="skyblue3");
#v-
\seealso{grace.get_colors, grace.plot}
\done