ploticus: libploticus api

## libploticus API | Welcome Gallery Handbook |
| Manual page for libploticus_API(PL)

## libploticus

Beginning in version 2.10, a simple C language API called libploticus is available for unix platforms. It has all of the funcionality of the pl program and is similarly covered by the General Public License.``

libploticus is built using `Makefile_api`.`` Applications linking to libploticus may need additional libraries such as `zlib`, but this depends on exactly how libploticus was built. The specifics are noted in `Makefile_api`.`` The externally visible symbols in libploticus begin with these prefixes: `ploticus`, `PL`, `TDH`, `DT`, and `GL`.``

No header file is required.``

All functions return 0 when successful, or a non-zero error code.``

## Program example

A similar example may be found in `./pltestsuite/api_examp.c`

       main()
       {
       int stat;
       stat = ploticus_init( "png", "bargraph.png" );
       stat += ploticus_arg( "-scale", "0.8" );
       stat += ploticus_begin();
       if( stat != 0 ) {
      	printf( "error in pl setup\n" );
           exit(1);
           }
       ploticus_execline( "#proc annotate" );
       ploticus_execline( "  location: 2 2" );
       ploticus_execline( "  text: hello" );
       ploticus_execline( "  world" );
       ploticus_execline( "" );
       ploticus_end();
       }

## libploticus API

`ploticus_init( char *device, char *outfilename )`

  Initialize, read your ploticus config file if any, and set the output `device` to one of `png`, `gif`, `x11`, `svg`, `jpeg`, `eps`, or `eps`.`` (Not all devices may be available, depending on the build.) `outfilename` is the pathname of the file where the result will be written. This function must be called first.`` Example:

         stat = ploticus_init( "png", "bargraph.png" );
         if( stat != 0 ) error

`ploticus_arg( name, value )`

  Get a pl command line argument.`` `name` specifies the argument name and `value` an argument value.`` If there is no argument value, `value` may be passed as `""`.`` All arguments are supported except `-f`, `-prefab`, and `-ver`.`` If needed, this function should be called after `ploticus_init()` but before any other ploticus function.`` It may be called as many times as necessary.`` Example:

          stat = ploticus_arg( "-debug", "" );
          stat += ploticus_arg( "-diagfile", "stdout" );
          stat += ploticus_arg( "-scale", "0.8" );
          if( stat != 0 ) error

`ploticus_begin( )`

  Perform further initializations that take into account command line arguments.`` This must be used after any calls to `ploticus_arg()` and before any other ploticus functions.
  Example: `ploticus_begin();`

`ploticus_execline( char *line )`

  Interpret one "raw" ploticus script line. `ploticus_execline()` is generally called multiple times, and allows ploticus scripts to be generated programatically.`` "Raw" ploticus script lines may contain no @variable references, and the only directives supported are `#proc`, `#procdef`, `#endproc`, `#clone` and `#saveas`.`` Lines may or may not be newline terminated.`` Intermingling with `ploticus_execscript()` is not allowed.`` Example:

          ploticus_execline( "#proc annotate" );
          ploticus_execline( "  location: 2 2" );
          ploticus_execline( "  text: hello" );
          ploticus_execline( "  world" );
          ploticus_execline( "" );

`ploticus_execscript( char *scriptfile, int prefabflag )`

  Interpret an entire ploticus script file. `scriptfile` is the name of the script file. `prefabflag` is `1`, then `scriptfile` should be a ploticus prefab name. If `prefabflag` is `0`, then `scriptfile` should be a pathname.`` Intermingling with `ploticus_execline()` is not allowed.``
  Example: `stat = ploticus_execscript( "vbars", 1 );`
  Example: `stat = ploticus_execscript( "/home/steve/plfiles/myscript.pl", 0 );`

`ploticus_getvar( char *name, char *value )`

  Get the contents of ploticus variable `name`.`` Result is copied into `value`.``
  Example: `stat = ploticus_getvar( "XFINAL", xf );`

`ploticus_setvar( char *name, char *value )`

  Set ploticus variable `name` to `value`.``

`gdImagePtr PLGG_getimg( int *width, int *height )`

  Returns a pointer to the working GD image, for situations where the host application wants to directly issue gd drawing calls.`` The `width` and `height` of the working image (in pixels) are also provided. Note that the result image is generally cropped based on the extent of ploticus drawing actions, before being written out.`` Only valid in applications built with GD, when ploticus was initialized with one of the GD image devices (eg. `png` or `jpeg`).``

`ploticus_end()`

  Finish up the graphic result (usually this involves writing it out to a file), and terminate ploticus. This must be the last ploticus function called.``
  data display engine
  Copyright Steve Grubb

Markup created by unroff 1.0, `` `` December 11, 2002.