## libploticus API

Version 2.32

Manual page for libploticus_API(PL)

This simple C language API has all of the funcionality of the pl program and is similarly covered by the General Public License.``

libploticus is built using `Makefile_api`.``

       make clean
       make -f 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.``

As of version 2.11 multiple sequential plot "jobs" can be performed by a single OS process.`` Each plot job should begin with a `ploticus_init()` call and terminate with a `ploticus_end()` call.

No attempt has been made to write libploticus as thread-safe.``

## Examples

Here's a simple example (it may be found in `./pltestsuite/api_examp.c`)

       main()
       {
       int stat;
       stat = ploticus_init( "png", "hello.png" );
       stat += ploticus_arg( "-scale", "0.8" );
       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();
       }

## Multi-job example

Another included example, which invokes a series of 25+ plot jobs, is in `./src/api_test.c To build:`

       make clean
       make -f Makefile_api
       make api_test -f Makefile_api

Then, go to the `pltestsuite` directory and type: `../src/api_test`

## 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 `swf`.`` (Not all devices may be available, depending on the build.) `outfilename` is the pathname of the file where the result will be written. Example:

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

`ploticus_arg( name, value )`

  Specify a pl command line argument.`` `name` specifies the argument name and `value` an argument value.`` If there is no argument value, `value` should 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( )`

  This function is no longer necessary. Old code that uses it will still be OK.``

  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. Typically called multiple times, allowing ploticus scripts to be generated programatically. "Raw" script lines can contain only these directives: `#proc`, `#procdef`, `#endproc`, `#clone` and `#saveas`. You can't use set, if/else, loops, or other flow-of-control directives (these types of things should be handled by your host application).`` Also, "raw" script lines do not undergo a variable-evaluation pass, so variables cannot be referenced, and `select` statements (etc.) that reference data field names should use one at sign (@) instead of two (@@). If your program needs to access a variable that has been set by the ploticus engine, use `ploticus_getvar()`, described below.``

  An alternative is to use `ploticus_execscript()` (described below) to execute an entire script file.`` You can't use both `ploticus_execline()` and `ploticus_execscript()` in the same application.``

  NOTE: If the `line` argument is passed as a constant it must not contain a trailing newline character.`` If passed as a variable then it doesn't matter.``

  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 or prefab.`` `scriptfile` is the name of the ploticus script file. There are no syntax limitations as with `ploticus_execline()`.`` `prefabflag` is `1`, then `scriptfile` is taken to be a ploticus prefab name such as `vbars`. If `prefabflag` is `0`, then `scriptfile` should be a pathname.``

  An alternative is to use `ploticus_execline()` (described above) to execute program-generated "raw" script lines one at a time.`` You can't use both `ploticus_execscript()` and `ploticus_execline()` in the same application.``

  Example: `stat = ploticus_execscript( "vbars", 1 );`
  Example: `stat = ploticus_execscript( "/home/steve/plfiles/myscript.pl", 0 );`

`ploticus_end()`

  Finish up the graphic result, write it to the output file, and free up allocated memory.``

## These functions are also available:

`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`).``
  data display engine
  Copyright Steve Grubb

Markup created by unroff 1.0, `` `` August 23, 2005.