Unique Features of the Ada bindings
Prev | Chapter 8. Ada Language | Next

## Unique Features of the Ada bindings

The Ada bindings have been augmented with a number of features which are intended to simplify the use of PLplot. They include high-level features for simplified plotting (such as easy foreground-background control, a collection of "simple plotters," and easy color map manipulations), integer options which have been given meaningful names, and a few other focused additions. Many users will find that they can do most of their work using the "simple plotters".

### High-level features for simplified plotting

#### Foreground-background control

##### Draw_On_Black, Draw_On_White

The default for PLplot is to draw its graphics on a black background. A white background can be used instead with `Draw_On_White` or reset to the original mode with `Draw_On_Black`. Each of these manipulates color map 0 by swapping black and white so that e.g.with `Draw_On_White`, formerly white lines on a black background automatically become black lines on a white background.

#### Simple Plotters

Several high-level but flexible plotters are available and more might be added in the future. It is expected that many users will find that these high-level routines are adequate for most of their day-to-day plotting.

##### Multiplot_Pairs

Plot up to five x-y pairs with easy labelling, coloring, line width and styles, justification, and zooming.

##### Simple_Plot

Plot up to five y's against a single x with easy labelling and automatic line colors and styles.

##### Simple_Plot_Log_X

Same as `Simple_Plot` but with logarithmic x-axis.

##### Simple_Plot_Log_Y

Same as `Simple_Plot` but with logarithmic y-axis.

##### Simple_Plot_Log_XY

Same as `Simple_Plot` but with logarithmic x- and y-axes.

##### Simple_Plot_Pairs

Plot up to five x-y pairs with easy labelling and automatic line colors and styles.

##### Single_Plot

Plot a single x-y pair with flexible labels, axis styles, colors, line width and style, justification, and zooming.

##### Simple_Contour

Make a contour plot with labels

##### Simple_Mesh_3D

Easy 3D mesh plot with labels, zooming, and perspective controls

##### Simple_Surface_3D

Easy 3D surface plot with labels, zooming, and perspective controls

#### Simple color map manipulations

PLplot provides extensive manipulation and control of two separate color maps, color map 0 and color map 1. The Ada binding makes basic manipulations easier and also adds facilities for making snapshots of color map 0 so that any state of the map can easily be restored later. An initial snapshot is taken when the package is initialized so that the default color settings can always be restored after having been changed.

Another set of features lets the user reset the 16 individual colors in color map 0 after a color definition has been changed. It is important to note that while `Set_Pen_Color(Red)` (`plcol0` in the traditional binding) normally does what it says, `Red` simply has the value `1`. If the user changes the color map so that `1` corresponds to another color, then `Set_Pen_Color(Red)` will draw in that color instead of red. To always assure that red is drawn even if the color map has been changed for integer `1`, use `Set_Pen_Color(Reset_Red)` instead. These 16 "reset" functions return the appropriate default integer for the specified color but also reset that slot in the color table so that a subsequent call such as `Set_Pen_Color(Red)` will also cause drawing in red.

Color map 1 also gets a easy-to-use makeover for Ada users. There are several prebuilt color themes that are useful for quickly making surface and mesh plots, `Color_Themes_For_Map_1_Type`. These color themes can be quickly applied with `Quick_Set_Color_Map_1`.

Miscellaneous other Ada features include a prebuilt mask function for `Shade_Regions` that does no masking; perhaps the most useful purpose is to provide a template for writing mask functions that do mask. And there is a handy function for calculating the contour levels for making contour plots.

- Color table snapshots

  `Make_Snapshot_Of_Color_Map_0`

  `Restore_Snapshot_Of_Color_Map_0`

  `Restore_Default_Snapshot_Of_Color_Map_0`

- Color resetting functions for the 16 colors of color map 0

  `Reset_Black, Reset_Red, ..., Reset_White`

- Easy manipulation of color map 1

  Prebuilt color themes for color map 1: `Color_Themes_For_Map_1_Type`

  Quick application of prebuilt color themes: `Quick_Set_Color_Map_1`

- Other features

  A prebuilt mask function for `Shade_Regions` that does no masking: `Mask_Function_No_Mask`

  An easy way to calculate an array of contour levels for contour plots: `Calculate_Contour_Levels`

### Integer Options Given Ada Names

The C version of PLplot uses a number of integers to mean specific things. Unfortunately, the meaning is lost when it it consigned to being a mere integer with no name. The Ada binding partially rectifies this situation by giving names to these integer constants. The integer can still be used if desired. (A more complete and safer rectification would use enumerated types.)

Below is a listing of at least the contexts in which these "re-namings" have been applied. In some cases the entire range of values is listed, but if there are more than about four such values for each context, only a sampling is given.

Instances

- Colors: Plot_Color_Type

  `0` is Black, `1` is Red, etc

- Justification for plots: `Justification_Type`

  `User_Justified`

  `Not_Justified`

  `Justified`

  `Justified_Square_Box`

- Axis styles: `Axis_Style_Type`

  `Linear_Major_Grid`

  `Linear_Minor_Grid`

  etc.

- Font styles: `Font_Style_Type`

  `Normal_Font`

  `Roman_Font`

  `Italic_Font`

  `Script_Font`

- Character sets: `Character_Set_Type`

  `Standard_Character_Set`

  `Extended_Character_Set`

- Plot orientation: `Orientation_Type`

  `Landscape`

  `Portrait`

- Modes for parsing command line arguments: `Parse_Mode_Type`

  E.g. `PL_PARSE_PARTIAL`

- Descriptions of map outlines (continents, states, etc.): `Map_Type`

  `Continents`

  `USA_and_States`

  `Continents_and_Countries`

  `USA_States_and_Continents`

- Various style and view options for 3D and surface plots

  E.g. `Lines_Parallel_To_X`

- Kind of gridding algorithm for interpolating 2D data to a grid: `Gridding_Algorithm_Type`

  E.g. `Grid_Bivariate_Cubic_Spline_Approximation`

- Flags for histogram style

  E.g. `Histogram_Default`

- Flags for histogram binning

  E.g. `Bin_Default`

- Names for color space models

  Hue, Lightness, Saturation: `HLS`

  Red, Green, Blue: `RGB`

### One-offs

To provide convenient string handling in a fashion that is familiar to Ada programmers, function versions which return a `String` type are provided of `Get_Device_Name`, `Get_Version_Number`, and `Get_Output_File_Name` (`plgdev`, `plgver`, and `plgfnam` in the traditional binding). These functions replace the procedure-style subprograms that are described in the C API documentation.

Overloaded `Set_Line_Style` (`plstyl` in the traditional binding) with a version that takes a single argument, `Default_Continuous_Line`. This replaces the awkward situation of calling the normal versions of these procedures with unused arguments simply to set the line style to the default, continuous, line.

The contour plotter `Contour_Plot_Irregular_Data` (`plfcont` in the traditional binding) is provided for making contour plots from irregularly spaced data. This feature is not documented in the PLplot API documentation.

The custom label function `Set_Custom_Label` (`plslabelfunc` in the traditional binding) can be called with null arguments to revert to using the default labelling scheme. Alternately, an Ada-only procedure with no arguments, `Use_Default_Labels`, is provided. See Ada example 19 (`x19a.adb` or `xthick19a.adb`) for a usage example.

The custom coordinate transform setter, `Set_Custom_Coordinate_Transform`, (`plstransform` in the traditional binding) can be called with null arguments to clear any previous custom coordinate transforms that the user has set, thus reverting to the default coordinate transform. Alternately, an Ada-only procedure with no arguments, `Clear_Custom_Coordinate_Transform`, is provided. See Ada example 19 (`x19a.adb` or `xthick19a.adb`) for a usage example.

The procedure `Set_Arrow_Style_For_Vector_Plots` (`plsvect` in the traditional binding) normally is called to define the shape of an arrow in vector plots. However, calling it with null pointer arguments (`System.Null_Address`) in place of the `Real_Vector` arrays and `False` for the `Fill_Arrow` argument causes the arrow shape to be reset to the default shape; this is implemented in Ada as an overloaded procedure in order to be consistent with the C API but is rather awkward. So there are two additional procedures that are added for the convenience of Ada programmers: Reset_Vector_Arrow_Style and plsvect, both without arguments, both available in both bindings, and the latter an overload of the normal arrow-setting procedure.

The procedures `Plot_Shapefile` and `Plot_Shapefile_World` (`plmapfill` ) and `plmapline` in the traditional binding) are each provided an overloaded version allowing either an array of integers or a null pointer to be passed for the last argument, so that the documentation makes sense. An additional related procedure is provided in each case, `Plot_Shapefile_All` and `Plot_Shapefile_World_All` (identically named in the traditional binding) for the case when a null pointer would otherwise be passed, thus allowing the Ada programmer a way to specify "plot all the Shapefile elements" without having to conjure a null pointer. See Example 19.

Prev | Up | Next
How to use the Ada bindings | Home | Parts That Retain a C Flavor