# SciPlot Widget Programmer's Reference

- Usage
- Widget Properties
- Color
- Fonts
- Point Styles
- Line Styles
- PostScript Output
- Public Functions
  - Refresh Functions
  - Color Functions
  - Data Manipulation Functions
  - Graph Control Functions
  - Hardcopy/Output Functions
- Known Issues

- Back to SciPlot home page

## Usage

Link against `libsciplot` and include the header: ``

#include "SciPlot.h"

The pkg-config name is `sciplot` (once installed); for an uninstalled build, pass the compiler and linker flags from `pkg-config gtk4 cairo pangocairo`.

Create the widget and add it to your GTK4 widget hierarchy in the normal way: ``

GtkWidget *plot = sciplot_widget_new();
gtk_widget_set_size_request(plot, 500, 400);
/* set initial properties */
sciplot_widget_set_plot_title(plot, "Demo of Plot Widget");
sciplot_widget_set_xlabel(plot, "X Axis (units)");
sciplot_widget_set_ylabel(plot, "Y Axis (units)");
sciplot_widget_set_chart_type(plot, XtPOLAR);
sciplot_widget_set_degrees(plot, TRUE);
/* add to parent container */
gtk_box_append(GTK_BOX(box), plot);

Data is plotted in groups called lists. Each list consists of a set of coordinates connected by a line, sharing a point style, point colour, line style, line colour, and legend label. Data is added via convenience functions only. ``

double rlist[] = {14., 18., 22., 26., SCIPLOT_SKIP_VAL, 30., 34., 38., 42.};
double tlist[] = {30., 60., 90., 120., SCIPLOT_SKIP_VAL, 150., 180., 270., 355.};
int line1 = SciPlotListCreateDouble(plot, 9, rlist, tlist, "List 1");

The `SCIPLOT_SKIP_VAL` marker causes a break in the line, producing disjoint segments.

Changes are not visible until `SciPlotUpdate()` is called.

## Widget Properties

Properties are set and retrieved with explicit functions of the form `sciplot_widget_set_name()` and `sciplot_widget_get_name()`. The defaults match the original Xt resource defaults.

Set function | Get function | Type | Default
--- | --- | --- | ---
sciplot_widget_set_axis_font | — | int (font flags) | XtFONT_TIMES|10
sciplot_widget_set_chart_type | — | int | XtCARTESIAN
sciplot_widget_set_degrees | — | gboolean | TRUE
sciplot_widget_set_draw_major | sciplot_widget_get_draw_major | gboolean | TRUE
sciplot_widget_set_draw_major_tics | — | gboolean | TRUE
sciplot_widget_set_draw_minor | sciplot_widget_get_draw_minor | gboolean | TRUE
sciplot_widget_set_draw_minor_tics | — | gboolean | TRUE
sciplot_widget_set_label_font | — | int (font flags) | XtFONT_TIMES|18
sciplot_widget_set_legend_through_plot | — | gboolean | FALSE
sciplot_widget_set_margin | — | int (pixels) | 5
sciplot_widget_set_monochrome | — | gboolean | FALSE
sciplot_widget_set_plot_title | sciplot_widget_get_plot_title | const char * | "Plot"
sciplot_widget_set_show_legend | sciplot_widget_get_show_legend | gboolean | TRUE
sciplot_widget_set_show_title | sciplot_widget_get_show_title | gboolean | TRUE
sciplot_widget_set_show_xlabel | sciplot_widget_get_show_xlabel | gboolean | TRUE
sciplot_widget_set_show_ylabel | sciplot_widget_get_show_ylabel | gboolean | TRUE
sciplot_widget_set_title_font | — | int (font flags) | XtFONT_HELVETICA|24
sciplot_widget_set_title_margin | — | int (pixels) | 16
sciplot_widget_set_xaxis_numbers | sciplot_widget_get_xaxis_numbers | gboolean | TRUE
sciplot_widget_set_xlabel | sciplot_widget_get_xlabel | const char * | "X Axis"
sciplot_widget_set_xlog | sciplot_widget_get_xlog | gboolean | FALSE
sciplot_widget_set_xorigin | sciplot_widget_get_xorigin | gboolean | FALSE
sciplot_widget_set_yaxis_numbers | sciplot_widget_get_yaxis_numbers | gboolean | TRUE
sciplot_widget_set_ylabel | sciplot_widget_get_ylabel | const char * | "Y Axis"
sciplot_widget_set_ylog | sciplot_widget_get_ylog | gboolean | FALSE
sciplot_widget_set_y_numbers_horizontal | — | gboolean | TRUE
sciplot_widget_set_yorigin | sciplot_widget_get_yorigin | gboolean | FALSE

chart_type
  XtCARTESIAN (x/y plot) or XtPOLAR (polar plot).

degrees
  Polar angle unit: TRUE = degrees, FALSE = radians.

draw_major / draw_minor
  Show major/minor gridlines.

draw_major_tics / draw_minor_tics
  Show major/minor tick marks on the axes.

label_font
  Font for axis labels and tick-mark numbers (see Fonts).

legend_through_plot
  If TRUE, the legend box overlaps the plot area instead of consuming space beside it.

margin
  Spacing in pixels between the plot and the widget border.

monochrome
  If TRUE, ignores per-list colours and draws everything in the foreground colour.

plot_title
  Title string drawn along the bottom of the widget.

show_legend / show_title / show_xlabel / show_ylabel
  Toggle visibility of each element.

title_font
  Font for the plot title.

title_margin
  Spacing in pixels between the plot area and the title.

xaxis_numbers / yaxis_numbers
  Show numeric labels on each axis. xaxis_numbers also controls radial labels in polar mode.

xlabel / ylabel
  (Cartesian only.) Axis label strings.

xlog / ylog
  (Cartesian only.) Logarithmic axis. Points with non-positive values on a log axis are not plotted.

xorigin / yorigin
  (Cartesian only.) Force the corresponding axis to pass through zero.

y_numbers_horizontal
  (Cartesian only.) If TRUE, Y-axis tick labels are drawn horizontally.

## Color

Colors are referenced by integer IDs returned from the allocation functions. Two colours are pre-allocated at widget creation:

ID | Colour
--- | ---
0 | white (background)
1 | black (foreground)

User colours start at index 2. Color names follow the CSS/GDK convention accepted by `gdk_rgba_parse()` (e.g., `"red"`, `"#ff8000"`, `"rgb(0,128,255)"`).

## Fonts

Fonts are specified by logically OR-ing an `XtFONT_*` family constant with optional style flags and a point size:

Constant | Pango family
--- | ---
XtFONT_TIMES | Times New Roman
XtFONT_COURIER | Courier New
XtFONT_HELVETICA | Helvetica
XtFONT_LUCIDA | Lucida Bright
XtFONT_LUCIDASANS | Lucida Sans
XtFONT_NCSCHOOLBOOK | Century Schoolbook L

Style constant | Effect
--- | ---
XtFONT_BOLD | Bold weight
XtFONT_ITALIC | Italic style
XtFONT_BOLD_ITALIC | Bold and italic (= XtFONT_BOLD|XtFONT_ITALIC)

Examples:

12-point Times, bold:
  `XtFONT_TIMES|XtFONT_BOLD|12`
10-point Courier:
  `XtFONT_COURIER|10`
16-point Lucida, bold italic:
  `XtFONT_LUCIDA|XtFONT_BOLD_ITALIC|16`

If a requested font family is not installed, Pango will substitute the nearest available alternative.

## Point Styles

Constant | Description
--- | ---
XtMARKER_NONE | no marker
XtMARKER_CIRCLE | open circle
XtMARKER_SQUARE | open square
XtMARKER_UTRIANGLE | triangle pointing up
XtMARKER_DTRIANGLE | triangle pointing down
XtMARKER_LTRIANGLE | triangle pointing left
XtMARKER_RTRIANGLE | triangle pointing right
XtMARKER_DIAMOND | diamond
XtMARKER_HOURGLASS | hourglass
XtMARKER_BOWTIE | bowtie
XtMARKER_FCIRCLE | filled circle
XtMARKER_FSQUARE | filled square
XtMARKER_FUTRIANGLE | filled triangle up
XtMARKER_FDTRIANGLE | filled triangle down
XtMARKER_FLTRIANGLE | filled triangle left
XtMARKER_FRTRIANGLE | filled triangle right
XtMARKER_FDIAMOND | filled diamond
XtMARKER_FHOURGLASS | filled hourglass
XtMARKER_FBOWTIE | filled bowtie
XtMARKER_DOT | small filled dot

## Line Styles

Constant | Description
--- | ---
XtLINE_NONE | no line (points only)
XtLINE_SOLID | solid line
XtLINE_DOTTED | dotted line
XtLINE_WIDEDOT | widely-spaced dotted line

## PostScript Output

EPS output is generated via Cairo's PS surface and faithfully reproduces the on-screen plot including all colours. Both `SciPlotPSCreate` and `SciPlotPSCreateColor` produce colour output (the distinction is retained for API compatibility).

## Public Functions

All functions take `GtkWidget *w` as their first argument (the SciPlot widget instance). Changes to data or styles are not visible until `SciPlotUpdate()` is called.

- ### Refresh Functions

  `void SciPlotUpdate(GtkWidget *w)`
    Recalculates all internal layout and redraws the plot. Call after adding, deleting, or modifying lists, or after changing any property.

  `gboolean SciPlotQuickUpdate(GtkWidget *w)`
    Faster redraw intended for real-time use. Skips full recalculation; only redraws the data area. Returns TRUE if any point lies outside the current axis range (indicating that a full `SciPlotUpdate()` is needed).

- ### Color Functions

  `int SciPlotAllocNamedColor(GtkWidget *w, const char *name)`
    Allocates a colour by CSS name (e.g., `"red"`, `"#3080ff"`). Returns the colour ID (> 1) on success, or 1 (foreground) on failure.

  `int SciPlotAllocRGBColor(GtkWidget *w, int r, int g, int b)`
    Allocates a colour from 0–255 integer components. Returns the colour ID.

  `void SciPlotSetBackgroundColor(GtkWidget *w, int color)`
    Sets the widget background to the given colour ID.

  `void SciPlotSetForegroundColor(GtkWidget *w, int color)`
    Sets the default foreground (axes, labels, legend outline) to the given colour ID.

- ### Data Manipulation Functions

  All creation functions return an integer list ID used by subsequent calls. Pass `num=0` and `NULL` arrays to create an empty list and populate it incrementally with `SciPlotListAddFloat` etc.

  `int SciPlotListCreateFloat(GtkWidget *w, int num, float *xlist, float *ylist, const char *legend)`
    Creates a list from float arrays. Initial style: black points (circle) and line (solid).

  `int SciPlotListCreateDouble(GtkWidget *w, int num, double *xlist, double *ylist, const char *legend)`
    Same, for double arrays.

  `int SciPlotListCreateFromData(GtkWidget *w, int num, real *xlist, real *ylist, const char *legend, int pcolor, int pstyle, int lcolor, int lstyle)`
    Creates a list from `real` (float) arrays with explicit style.

  `void SciPlotListUpdateFloat(GtkWidget *w, int id, int num, float *xlist, float *ylist)`
    Replaces the data in list id with new float arrays.

  `void SciPlotListUpdateDouble(GtkWidget *w, int id, int num, double *xlist, double *ylist)`
    Same, for double arrays.

  `void SciPlotListAddFloat(GtkWidget *w, int id, int num, float *xlist, float *ylist)`
    Appends float data to list id.

  `void SciPlotListAddDouble(GtkWidget *w, int id, int num, double *xlist, double *ylist)`
    Same, for double arrays.

  `void SciPlotListDelete(GtkWidget *w, int id)`
    Removes list id from the widget.

  `void SciPlotListSetStyle(GtkWidget *w, int id, int pcolor, int pstyle, int lcolor, int lstyle)`
    Sets point colour, point style, line colour, and line style for list id. Pass -1 for any parameter to leave it unchanged.

  `void SciPlotListSetMarkerSize(GtkWidget *w, int id, float size)`
    Sets the marker size (pixels) for list id.

- ### Graph Control Functions

  `void SciPlotSetXAutoScale(GtkWidget *w)`
    (Cartesian.) Restores automatic X-axis scaling from data range.

  `void SciPlotSetXUserScale(GtkWidget *w, double min, double max)`
    (Cartesian, non-log.) Forces the X axis to display [min, max].

  `void SciPlotSetYAutoScale(GtkWidget *w)`
    (Cartesian.) Restores automatic Y-axis scaling.

  `void SciPlotSetYUserScale(GtkWidget *w, double min, double max)`
    (Cartesian, non-log.) Forces the Y axis to display [min, max].

- ### Hardcopy/Output Functions

  `gboolean SciPlotPSCreate(GtkWidget *w, const char *filename)`
    Writes an EPS file of the current plot. Returns TRUE on success.

  `gboolean SciPlotPSCreateColor(GtkWidget *w, const char *filename)`
    Same as SciPlotPSCreate (both produce colour output).

  `void SciPlotExportData(GtkWidget *w, FILE *fd)`
    Writes a tab-separated summary of all list data to the already-open file fd, importable by most graphing tools.

## Known Issues

- Font fallback follows Pango/fontconfig rules; the requested family may be substituted silently if not installed.
- PostScript output relies on Cairo's font embedding; complex scripts or unusual fonts may not embed correctly in all viewers.

SciPlot : Programmer's Reference | Demo Programs

Originally by Rob McMullen. GTK4 port by Barak A. Pearlmutter. Updated: 2 Jun 2026