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

Line Styles

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.