Reference
The following page outlines the application programming interface for the Aplot library.
Constants
The following constants are used by the library:
Plot Type
| APLOT_STYLE_LINE | Plot series as continuous line |
| APLOT_STYLE_DOT | Plot series as a 5-pixel square dot |
| APLOT_STYLE_PIXEL | Plot series as a single pixel per point |
| APLOT_STYLE_BAR | Plot series as a bar chart |
Plot Management
initialize_plot
Fortran function initialize_plot ()
Description
Initializes a new plot.
Return Value
Fortran type(aplot_t)
A derived type that internally represents the plot itself
destroy_plot
Fortran subroutine destroy_plot (p)
Description
Destroys an existing plot, freeing any memory associated with it.
Arguments
| Argument | Fortran Type | Description |
| p | type(aplot_t) | An existing plot variable |
display_plot
Fortran subroutine display_plot (p)
or
Fortran (Windows Only) subroutine display_plot (p, async)
Description
Displays a plot and blocks program execution until the user closes the window. The plot must be configured entirely prior to calling this routine.
On Windows, the optional async argument, when true, will cause the routine to return from the call to display_plot immediately.
Arguments
| Argument | Fortran Type | Description |
| p | type(aplot_t) | An existing plot variable |
| async | logical | Optional, Windows Only: when .true., return from this call immediately. This call will block if omitted or .false. |
set_title
Fortran subroutine set_title (p, nm)
Description
Sets the title displayed above the plot.
Arguments
| Argument | Fortran Type | Description |
| p | type(aplot_t) | An existing plot variable |
| nm | character(*) | The label to apply to the plot |
Plot Data
add_dataset
Fortran subroutine add_dataset (p, x, y)
Description
Adds a dataset to an existing plot variable.
Arguments
| Argument | Fortran Type | Description |
| p | type(aplot_t) | An existing plot variable |
| x | real, dimension(:) | A one-dimensional array of x-axis points |
| y | real, dimension(:) | A one-dimensional array of y-axis points corresponding to each point in x |
set_seriescolor
Fortran subroutine set_seriescolor (p, i, red, green, blue)
Description
Sets the color for this data set.
Arguments
| Argument | Fortran Type | Description |
| p | type(aplot_t) | An existing plot variable |
| i | integer | The zero-indexed series to label |
| r | integer | Red value of the color from 0 to 255 |
| g | integer | Green value of the color from 0 to 255 |
| b | integer | Blue value of the color from 0 to 255 |
set_serieslabel
Fortran subroutine set_serieslabel (p, i, nm)
Description
Assigns a label to the ith series. The series are zero-indexed (i.e. the first series added to the plot is i=0).
Arguments
| Argument | Fortran Type | Description |
| p | type(aplot_t) | An existing plot variable |
| i | integer | The zero-indexed series to label |
| nm | character(*) | The label to apply to the series |
set_seriestype
Fortran subroutine set_seriestype (p, i, tp)
Description
Configures the type of plot for a given series using the constants APLOT_STYLE_LINE, APLOT_STYLE_DOT, APLOT_STYLE_PIXEL, and APLOT_STYLE_BAR. The series are zero-indexed (i.e. the first series added to the plot is i=0).
Arguments
| Argument | Fortran Type | Description |
| p | type(aplot_t) | An existing plot variable |
| i | integer | The zero-indexed series to label |
| tp | integer | The desired series type |
Axis Configuration
set_xautoscale
Fortran subroutine set_xautoscale (p)
Description
Enable autoscaling of the x-axis (the default configuration).
Arguments
| Argument | Fortran Type | Description |
| p | type(aplot_t) | An existing plot variable |
set_yautoscale
Fortran subroutine set_yautoscale (p)
Description
Enable autoscaling of the y-axis (the default configuration).
Arguments
| Argument | Fortran Type | Description |
| p | type(aplot_t) | An existing plot variable |
set_xlabel
Fortran subroutine set_xlabel (p, nm)
Description
Set the desired label for the x-axis.
Arguments
| Argument | Fortran Type | Description |
| p | type(aplot_t) | An existing plot variable |
| nm | character(*) | The label to apply to the x-axis |
set_ylabel
Fortran subroutine set_ylabel (p, nm)
Description
Set the desired label for the y-axis.
Arguments
| Argument | Fortran Type | Description |
| p | type(aplot_t) | An existing plot variable |
| nm | character(*) | The label to apply to the y-axis |
set_xlinear
Fortran subroutine set_xlinear (p)
Description
Configures the x axis to a linear scale (default)
Arguments
| Argument | Fortran Type | Description |
| p | type(aplot_t) | An existing plot variable |
set_xlogarithmic
Fortran subroutine set_xlogarithmic (p, base)
Description
Configures the x axis to a logarithmic scale with an optional base specified. If not present, the base is assumed to be 10.0.
Arguments
| Argument | Fortran Type | Description |
| p | type(aplot_t) | An existing plot variable |
| base | real | Optional: base for logarithmic scale |
set_ylinear
Fortran subroutine set_ylinear (p)
Description
Configures the y axis to a linear scale (default)
Arguments
| Argument | Fortran Type | Description |
| p | type(aplot_t) | An existing plot variable |
set_ylogarithmic
Fortran subroutine set_ylogarithmic (p, base)
Description
Configures the y axis to a logarithmic scale with an optional base specified. If not present, the base is assumed to be 10.0.
Arguments
| Argument | Fortran Type | Description |
| p | type(aplot_t) | An existing plot variable |
| base | real | Optional: base for logarithmic scale |
set_xscale
Fortran subroutine set_xscale (p, vmin, vmax)
Description
Manually sets the scaling for the x-axis
Arguments
| Argument | Fortran Type | Description |
| p | type(aplot_t) | An existing plot variable |
| vmin | real | The minimum value represented on the x-axis |
| vmax | real | The maximum value represented on the x-axis |
set_yscale
Fortran subroutine set_yscale (p, vmin, vmax)
Description
Manually sets the scaling for the y-axis
Arguments
| Argument | Fortran Type | Description |
| p | type(aplot_t) | An existing plot variable |
| vmin | real | The minimum value represented on the y-axis |
| vmax | real | The maximum value represented on the y-axis |
Windows-Specific Functionality
Aplot for Windows offers some additional functionality due to the architecture of
the Windows user interface. Specifically, Aplot can be operated in an asynchronous
mode where the calling program can continue running after displaying a plot. These
plots can be programatically saved and closed.
close_plot
Fortran subroutine close_plot (p)
Description
Closes the plot window associated with the specified plot. This routine is only useful when the async argument to display_plot is .true.
Arguments
| Argument | Fortran Type | Description |
| p | type(aplot_t) | An existing plot variable |
save_plot
Fortran subroutine save_plot (p, filename)
Description
Saves the currently displayed plot specified by the p argument. This function will fail if the plot window is not currently open.
Arguments
| Argument | Fortran Type | Description |
| p | type(aplot_t) | An existing plot variable |
| filename | character(len=*) | Optional: Filename to save a bitmap image of the file. A file selection dialog will open if omitted. |
embed_plot
Fortran subroutine embed_plot (p, window_id, x, y, width, height)
Description
Draws the plot at the specified coordinates with the specified dimensions inside an existing AppGraphics window. This functionality requires that a window already be open via AppGraphics calls.
When called, the plot is immediately drawn to the current active page in AppGraphics exactly once. When complete, any viewport present at the beginning of the call will be eliminated, and colors and fonts consistent with Aplot’s default styling will be set.
This call notably does not automatically update the plot’s display. If the user needs to refresh the window or implement resizing, the embed_plot routine will need to be called again to place the resized and repositioned graph manually.
The coordinates specified will provide an area in which Aplot can work; they do not define the actual area defined by plot axes due to the presence of margins, labels, etc. in an Aplot plot.
Arguments
| Argument | Fortran Type | Description |
| p | type(aplot_t) | An existing plot variable |
| window_id | integer | The AppGraphics window identifier in which to draw the plot |
| x | integer | The x coordinate of the left side of the plot area |
| y | integer | The y coordinate of the top side of the plot area |
| width | integer | The width of the plot area |
| height | integer | The height of the plot area |
