- NAME
- SYNOPSIS
- DESCRIPTION
- FUNCTIONS

- dev
- new_window
- close_window
- _get_windownumber
- focus_window
- window_list

# NAME

      PDL::Graphics::PGPLOT - PGPLOT enhanced interface for PDL

# SYNOPSIS

     perldl> $a = pdl [1..100]
     perldl> $b = sqrt($a)
     perldl> line $b
     perldl> hold
     Graphics on HOLD
     perldl> $c = sin($a/10)*2 + 4
     perldl> line $c

# DESCRIPTION

`PDL::Graphics::PGPLOT` is a convenience interface to the PGPLOT commands, implemented using the object oriented PGPLOT plotting package in the PDL::Graphics::PGPLOT::Window manpage. See the documentation for that package for in-depth information about the usage of these commands and the options they accept.

The list of currently availably commands:

     imag       -  Display an image (uses pgimag()/pggray() as appropriate)
     im         -  Shorthand to display an image with aspect ratio of 1
     ctab       -  Load an image colour table
     ctab_info  -  Get information about currently loaded colour table
     line       -  Plot vector as connected points
     points     -  Plot vector as points
     errb       -  Plot error bars
     cont       -  Display image as contour map
     bin        -  Plot vector as histogram (e.g. bin(hist($data)) )
     hi2d       -  Plot image as 2d histogram (not very good IMHO...)
     poly       -  Draw a polygon
     vect       -  Display 2 images as a vector field
     text       -  Write text in the plot area
     label_axes -  Print axis titles
     legend     -  Create a legend with different texts, linestyles etc.
     cursor     -  Interactively read cursor positions.
     circle     -  Draw a circle
     ellipse    -  Draw an ellipse.

Device manipulation commands:

     hold         -  Hold current plot window range - allows overlays etc.
     release      -  Release back to autoscaling of new plot window for each
                     command
     rel          -  short alias for 'release'
     env          -  Define a plot window, put on 'hold'
     dev          -  Explicitly set a new PGPLOT graphics device
     new_window   -  Create a new plot window (use of dev is recommended)
     focus_window -  Change focus to a new window
     window_list  -  Get a list of currently exisiting plot windows
     close_window -  Close an open window

# FUNCTIONS

The following is a list of the functions that are private to this package, for the other functions please read the the PDL::Graphics::PGPLOT::Window manpage documentation.

## dev

Open PGPLOT graphics device

     Usage: dev $device, [$nx,$ny, $opt];

`$device` is a PGPLOT graphics device such as ``/xserve'' or ``/ps'', if omitted defaults to last used device (or value of env var `PGPLOT_DEV` if first time). `$nx`, `$ny` specify sub-panelling. The function returns the id of the newly created window - this can subsequently be used as argument to `focus_window` to select the window.

The result of this command can be modified using options. The options recognised are the same as for `new_window` - which primarily and in addition it is possible to set the default values for a window that are defined in the PDL::PGPLOTOptions manpage, see this for details but see below for a synopsis.

In addition `dev` recognises the option `NewWindow` which allows the user to specify that a `dev` command is to create a new window rather than closing the previous. This allows a large number of output destinations to be open at the same time, which occasionally can be convenient.

Here is a quick summary of the most useful additional options that can be given:

Device
  Alternative to `$device`.

AspectRatio
  The aspect ratio of the output window

WindowWidth
  The width of the plot window in inches

AxisColour
  The axis colour to be used as default for plots in this window. In the same way it is possible to set the default character size (`CharSize`) and axis and box styles. See the PDL::Graphics::PGPLOTOptions manpage for details.

WindowName
  The name of a window. This name can subsequently be used to refer to the window instead of its ID, making interactive use somewhat more intuitive.

To open a X-window output that will stay on screen:

      $win = dev('/xs');

To open two windows, one small and square, one large and wide:

      $win1 = dev('/xs', {Aspect => 1, WindowWidth => 4});
      $win2 = dev('/xs', {Aspect => 0.5, WindowWidth => 10});

## new_window

Open a PGPLOT graphics device

      $win = new_window($dev, $nx, $ny, $opt);

This function is identical to the dev manpage except that it always creates a new window. This means that the user is required to close all windows explicitly using the close_window manpage. All functionality is otherwise like `dev` so see the documentation for the dev manpage for details of use.

## close_window

Close a PGPLOT output device

     Usage: close_window($id)

This function closes a PGPLOT output device created with `dev` or `new_window`. It requires the id of the window to close. If `$id` is left undefined, the currently focussed window is deleted and focus is transferred to the lowest numbered window in existence. If many windows have been created and deleted this might not be what you expect, so it is recommended to make an explicit call to the focus_window manpage after any call to `close_window`.

## _get_windownumber

Internal function to obtain the ID of a window. This allows the user to refer to a window with its name.

## focus_window

Switch to another output window.

     Usage: focus_window($id);

This command is used to switch output focus to another window created by the dev manpage or the new_window manpage. The window can be referred to either by its ID or by its name.

      $win1 = dev('/xs', {WindowName => 'X-output'});
      $win2 = dev('test.ps/ps', {WindowName => 'PS-output'});

      focus_window('X-output');  # Or focus_window($win1);
      <.. Commands ..>
      focus_window($win2);       # Or focus_window('PS-output');
      <.. Commands ..>

## window_list

Return a list of ID numbers and names of the windows currently opened using the dev manpage or `new_window`.

     Usage: ($numbers, $names)=window_list();

`$numbers` and `$names` are anonymous arrays giving the ID numbers and names of the open windows respectively.