Debian Codegraph @

SciPlotProg.html

raw
1 <html><head><title>SciPlot Widget Programmer's Reference</title></head><body>
2 <h1><a name="top">SciPlot Widget Programmer's Reference</a></h1>
3
4 <ul>
5 <li><a href="#usage">Usage</a>
6 <li><a href="#props">Widget Properties</a>
7 <li><a href="#color">Color</a>
8 <li><a href="#font">Fonts</a>
9 <li><a href="#point">Point Styles</a>
10 <li><a href="#line">Line Styles</a>
11 <li><a href="#eps">PostScript Output</a>
12 <li><a href="#pub">Public Functions</a>
13 <ul>
14 <li><a href="#ref">Refresh Functions</a>
15 <li><a href="#colorfn">Color Functions</a>
16 <li><a href="#list">Data Manipulation Functions</a>
17 <li><a href="#graph">Graph Control Functions</a>
18 <li><a href="#output">Hardcopy/Output Functions</a>
19 </ul>
20 <li><a href="#bug">Known Issues</a>
21 </ul>
22
23 <ul><li><a href="SciPlot.html">Back to SciPlot home page</a></ul>
24
25 <p><hr><h2><a name="usage">Usage</a></h2>
26 <p>Link against <tt>libsciplot</tt> and include the header:
27
28 <code><dl>
29 <dt>#include "SciPlot.h"
30 </dl></code>
31
32 <p>The pkg-config name is <tt>sciplot</tt> (once installed); for an uninstalled
33 build, pass the compiler and linker flags from <tt>pkg-config gtk4 cairo
34 pangocairo</tt>.
35
36 <p>Create the widget and add it to your GTK4 widget hierarchy in the normal way:
37
38 <code><dl>
39 <dt>GtkWidget *plot = sciplot_widget_new();
40 <dt>gtk_widget_set_size_request(plot, 500, 400);
41 <dt>/* set initial properties */
42 <dt>sciplot_widget_set_plot_title(plot, "Demo of Plot Widget");
43 <dt>sciplot_widget_set_xlabel(plot, "X Axis (units)");
44 <dt>sciplot_widget_set_ylabel(plot, "Y Axis (units)");
45 <dt>sciplot_widget_set_chart_type(plot, XtPOLAR);
46 <dt>sciplot_widget_set_degrees(plot, TRUE);
47 <dt>/* add to parent container */
48 <dt>gtk_box_append(GTK_BOX(box), plot);
49 </dl></code>
50
51 <p>Data is plotted in groups called <i>lists</i>. Each list consists of a set
52 of coordinates connected by a line, sharing a point style, point colour, line
53 style, line colour, and legend label. Data is added via convenience functions
54 only.
55
56 <code><dl>
57 <dt>double rlist[] = {14., 18., 22., 26., SCIPLOT_SKIP_VAL, 30., 34., 38., 42.};
58 <dt>double tlist[] = {30., 60., 90., 120., SCIPLOT_SKIP_VAL, 150., 180., 270., 355.};
59 <dt>int line1 = SciPlotListCreateDouble(plot, 9, rlist, tlist, "List 1");
60 </dl></code>
61
62 <p>The <tt>SCIPLOT_SKIP_VAL</tt> marker causes a break in the line, producing
63 disjoint segments.
64
65 <p>Changes are not visible until <tt>SciPlotUpdate()</tt> is called.
66
67 <p><hr><h2><a name="props">Widget Properties</a></h2>
68 <p>Properties are set and retrieved with explicit functions of the form
69 <tt>sciplot_widget_set_<i>name</i>()</tt> and
70 <tt>sciplot_widget_get_<i>name</i>()</tt>.
71 The defaults match the original Xt resource defaults.
72
73 <table border>
74 <tr><th>Set function</th><th>Get function</th><th>Type</th><th>Default</th></tr>
75 <tr><td>sciplot_widget_set_axis_font</td><td>—</td><td>int (font flags)</td><td>XtFONT_TIMES|10</td></tr>
76 <tr><td>sciplot_widget_set_chart_type</td><td>—</td><td>int</td><td>XtCARTESIAN</td></tr>
77 <tr><td>sciplot_widget_set_degrees</td><td>—</td><td>gboolean</td><td>TRUE</td></tr>
78 <tr><td>sciplot_widget_set_draw_major</td><td>sciplot_widget_get_draw_major</td><td>gboolean</td><td>TRUE</td></tr>
79 <tr><td>sciplot_widget_set_draw_major_tics</td><td>—</td><td>gboolean</td><td>TRUE</td></tr>
80 <tr><td>sciplot_widget_set_draw_minor</td><td>sciplot_widget_get_draw_minor</td><td>gboolean</td><td>TRUE</td></tr>
81 <tr><td>sciplot_widget_set_draw_minor_tics</td><td>—</td><td>gboolean</td><td>TRUE</td></tr>
82 <tr><td>sciplot_widget_set_label_font</td><td>—</td><td>int (font flags)</td><td>XtFONT_TIMES|18</td></tr>
83 <tr><td>sciplot_widget_set_legend_through_plot</td><td>—</td><td>gboolean</td><td>FALSE</td></tr>
84 <tr><td>sciplot_widget_set_margin</td><td>—</td><td>int (pixels)</td><td>5</td></tr>
85 <tr><td>sciplot_widget_set_monochrome</td><td>—</td><td>gboolean</td><td>FALSE</td></tr>
86 <tr><td>sciplot_widget_set_plot_title</td><td>sciplot_widget_get_plot_title</td><td>const char *</td><td>"Plot"</td></tr>
87 <tr><td>sciplot_widget_set_show_legend</td><td>sciplot_widget_get_show_legend</td><td>gboolean</td><td>TRUE</td></tr>
88 <tr><td>sciplot_widget_set_show_title</td><td>sciplot_widget_get_show_title</td><td>gboolean</td><td>TRUE</td></tr>
89 <tr><td>sciplot_widget_set_show_xlabel</td><td>sciplot_widget_get_show_xlabel</td><td>gboolean</td><td>TRUE</td></tr>
90 <tr><td>sciplot_widget_set_show_ylabel</td><td>sciplot_widget_get_show_ylabel</td><td>gboolean</td><td>TRUE</td></tr>
91 <tr><td>sciplot_widget_set_title_font</td><td>—</td><td>int (font flags)</td><td>XtFONT_HELVETICA|24</td></tr>
92 <tr><td>sciplot_widget_set_title_margin</td><td>—</td><td>int (pixels)</td><td>16</td></tr>
93 <tr><td>sciplot_widget_set_xaxis_numbers</td><td>sciplot_widget_get_xaxis_numbers</td><td>gboolean</td><td>TRUE</td></tr>
94 <tr><td>sciplot_widget_set_xlabel</td><td>sciplot_widget_get_xlabel</td><td>const char *</td><td>"X Axis"</td></tr>
95 <tr><td>sciplot_widget_set_xlog</td><td>sciplot_widget_get_xlog</td><td>gboolean</td><td>FALSE</td></tr>
96 <tr><td>sciplot_widget_set_xorigin</td><td>sciplot_widget_get_xorigin</td><td>gboolean</td><td>FALSE</td></tr>
97 <tr><td>sciplot_widget_set_yaxis_numbers</td><td>sciplot_widget_get_yaxis_numbers</td><td>gboolean</td><td>TRUE</td></tr>
98 <tr><td>sciplot_widget_set_ylabel</td><td>sciplot_widget_get_ylabel</td><td>const char *</td><td>"Y Axis"</td></tr>
99 <tr><td>sciplot_widget_set_ylog</td><td>sciplot_widget_get_ylog</td><td>gboolean</td><td>FALSE</td></tr>
100 <tr><td>sciplot_widget_set_y_numbers_horizontal</td><td>—</td><td>gboolean</td><td>TRUE</td></tr>
101 <tr><td>sciplot_widget_set_yorigin</td><td>sciplot_widget_get_yorigin</td><td>gboolean</td><td>FALSE</td></tr>
102 </table>
103
104 <dl>
105 <p><dt>chart_type
106 <dd>XtCARTESIAN (x/y plot) or XtPOLAR (polar plot).
107
108 <p><dt>degrees
109 <dd>Polar angle unit: TRUE = degrees, FALSE = radians.
110
111 <p><dt>draw_major / draw_minor
112 <dd>Show major/minor gridlines.
113
114 <p><dt>draw_major_tics / draw_minor_tics
115 <dd>Show major/minor tick marks on the axes.
116
117 <p><dt>label_font
118 <dd>Font for axis labels and tick-mark numbers (see <a href="#font">Fonts</a>).
119
120 <p><dt>legend_through_plot
121 <dd>If TRUE, the legend box overlaps the plot area instead of consuming space beside it.
122
123 <p><dt>margin
124 <dd>Spacing in pixels between the plot and the widget border.
125
126 <p><dt>monochrome
127 <dd>If TRUE, ignores per-list colours and draws everything in the foreground colour.
128
129 <p><dt>plot_title
130 <dd>Title string drawn along the bottom of the widget.
131
132 <p><dt>show_legend / show_title / show_xlabel / show_ylabel
133 <dd>Toggle visibility of each element.
134
135 <p><dt>title_font
136 <dd>Font for the plot title.
137
138 <p><dt>title_margin
139 <dd>Spacing in pixels between the plot area and the title.
140
141 <p><dt>xaxis_numbers / yaxis_numbers
142 <dd>Show numeric labels on each axis. xaxis_numbers also controls radial labels in polar mode.
143
144 <p><dt>xlabel / ylabel
145 <dd>(Cartesian only.) Axis label strings.
146
147 <p><dt>xlog / ylog
148 <dd>(Cartesian only.) Logarithmic axis. Points with non-positive values on a log axis are not plotted.
149
150 <p><dt>xorigin / yorigin
151 <dd>(Cartesian only.) Force the corresponding axis to pass through zero.
152
153 <p><dt>y_numbers_horizontal
154 <dd>(Cartesian only.) If TRUE, Y-axis tick labels are drawn horizontally.
155 </dl>
156
157 <p><hr><h2><a name="color">Color</a></h2>
158 <p>Colors are referenced by integer IDs returned from the allocation functions.
159 Two colours are pre-allocated at widget creation:
160
161 <table border>
162 <tr><th>ID</th><th>Colour</th></tr>
163 <tr><td>0</td><td>white (background)</td></tr>
164 <tr><td>1</td><td>black (foreground)</td></tr>
165 </table>
166
167 <p>User colours start at index 2. Color names follow the CSS/GDK convention
168 accepted by <tt>gdk_rgba_parse()</tt> (e.g., <tt>"red"</tt>,
169 <tt>"#ff8000"</tt>, <tt>"rgb(0,128,255)"</tt>).
170
171 <p><hr><h2><a name="font">Fonts</a></h2>
172 <p>Fonts are specified by logically OR-ing an <tt>XtFONT_*</tt> family
173 constant with optional style flags and a point size:
174
175 <table border>
176 <tr><th>Constant</th><th>Pango family</th></tr>
177 <tr><td>XtFONT_TIMES</td><td>Times New Roman</td></tr>
178 <tr><td>XtFONT_COURIER</td><td>Courier New</td></tr>
179 <tr><td>XtFONT_HELVETICA</td><td>Helvetica</td></tr>
180 <tr><td>XtFONT_LUCIDA</td><td>Lucida Bright</td></tr>
181 <tr><td>XtFONT_LUCIDASANS</td><td>Lucida Sans</td></tr>
182 <tr><td>XtFONT_NCSCHOOLBOOK</td><td>Century Schoolbook L</td></tr>
183 </table>
184
185 <table border>
186 <tr><th>Style constant</th><th>Effect</th></tr>
187 <tr><td>XtFONT_BOLD</td><td>Bold weight</td></tr>
188 <tr><td>XtFONT_ITALIC</td><td>Italic style</td></tr>
189 <tr><td>XtFONT_BOLD_ITALIC</td><td>Bold and italic (= XtFONT_BOLD|XtFONT_ITALIC)</td></tr>
190 </table>
191
192 <p>Examples:
193 <dl>
194 <dt>12-point Times, bold: <dd><code>XtFONT_TIMES|XtFONT_BOLD|12</code>
195 <dt>10-point Courier: <dd><code>XtFONT_COURIER|10</code>
196 <dt>16-point Lucida, bold italic: <dd><code>XtFONT_LUCIDA|XtFONT_BOLD_ITALIC|16</code>
197 </dl>
198
199 <p>If a requested font family is not installed, Pango will substitute the
200 nearest available alternative.
201
202 <p><hr><h2><a name="point">Point Styles</a></h2>
203 <table border>
204 <tr><th>Constant</th><th>Description</th></tr>
205 <tr><td>XtMARKER_NONE</td><td>no marker</td></tr>
206 <tr><td>XtMARKER_CIRCLE</td><td>open circle</td></tr>
207 <tr><td>XtMARKER_SQUARE</td><td>open square</td></tr>
208 <tr><td>XtMARKER_UTRIANGLE</td><td>triangle pointing up</td></tr>
209 <tr><td>XtMARKER_DTRIANGLE</td><td>triangle pointing down</td></tr>
210 <tr><td>XtMARKER_LTRIANGLE</td><td>triangle pointing left</td></tr>
211 <tr><td>XtMARKER_RTRIANGLE</td><td>triangle pointing right</td></tr>
212 <tr><td>XtMARKER_DIAMOND</td><td>diamond</td></tr>
213 <tr><td>XtMARKER_HOURGLASS</td><td>hourglass</td></tr>
214 <tr><td>XtMARKER_BOWTIE</td><td>bowtie</td></tr>
215 <tr><td>XtMARKER_FCIRCLE</td><td>filled circle</td></tr>
216 <tr><td>XtMARKER_FSQUARE</td><td>filled square</td></tr>
217 <tr><td>XtMARKER_FUTRIANGLE</td><td>filled triangle up</td></tr>
218 <tr><td>XtMARKER_FDTRIANGLE</td><td>filled triangle down</td></tr>
219 <tr><td>XtMARKER_FLTRIANGLE</td><td>filled triangle left</td></tr>
220 <tr><td>XtMARKER_FRTRIANGLE</td><td>filled triangle right</td></tr>
221 <tr><td>XtMARKER_FDIAMOND</td><td>filled diamond</td></tr>
222 <tr><td>XtMARKER_FHOURGLASS</td><td>filled hourglass</td></tr>
223 <tr><td>XtMARKER_FBOWTIE</td><td>filled bowtie</td></tr>
224 <tr><td>XtMARKER_DOT</td><td>small filled dot</td></tr>
225 </table>
226
227 <p><hr><h2><a name="line">Line Styles</a></h2>
228 <table border>
229 <tr><th>Constant</th><th>Description</th></tr>
230 <tr><td>XtLINE_NONE</td><td>no line (points only)</td></tr>
231 <tr><td>XtLINE_SOLID</td><td>solid line</td></tr>
232 <tr><td>XtLINE_DOTTED</td><td>dotted line</td></tr>
233 <tr><td>XtLINE_WIDEDOT</td><td>widely-spaced dotted line</td></tr>
234 </table>
235
236 <p><hr><h2><a name="eps">PostScript Output</a></h2>
237 <p>EPS output is generated via Cairo's PS surface and faithfully reproduces the
238 on-screen plot including all colours. Both
239 <tt>SciPlotPSCreate</tt> and <tt>SciPlotPSCreateColor</tt> produce colour
240 output (the distinction is retained for API compatibility).
241
242 <p><hr><h2><a name="pub">Public Functions</a></h2>
243
244 <p>All functions take <tt>GtkWidget *w</tt> as their first argument (the
245 SciPlot widget instance). Changes to data or styles are not visible until
246 <tt>SciPlotUpdate()</tt> is called.
247
248 <ul>
249 <li><h3><a name="ref">Refresh Functions</a></h3>
250 <dl>
251 <p><dt><tt>void <b>SciPlotUpdate</b>(GtkWidget *w)</tt>
252 <dd>Recalculates all internal layout and redraws the plot. Call after adding,
253 deleting, or modifying lists, or after changing any property.
254
255 <p><dt><tt>gboolean <b>SciPlotQuickUpdate</b>(GtkWidget *w)</tt>
256 <dd>Faster redraw intended for real-time use. Skips full recalculation; only
257 redraws the data area. Returns TRUE if any point lies outside the current
258 axis range (indicating that a full <tt>SciPlotUpdate()</tt> is needed).
259 </dl>
260
261 <li><h3><a name="colorfn">Color Functions</a></h3>
262 <dl>
263 <p><dt><tt>int <b>SciPlotAllocNamedColor</b>(GtkWidget *w, const char *name)</tt>
264 <dd>Allocates a colour by CSS name (e.g., <tt>"red"</tt>, <tt>"#3080ff"</tt>).
265 Returns the colour ID (&gt; 1) on success, or 1 (foreground) on failure.
266
267 <p><dt><tt>int <b>SciPlotAllocRGBColor</b>(GtkWidget *w, int r, int g, int b)</tt>
268 <dd>Allocates a colour from 0–255 integer components. Returns the colour ID.
269
270 <p><dt><tt>void <b>SciPlotSetBackgroundColor</b>(GtkWidget *w, int color)</tt>
271 <dd>Sets the widget background to the given colour ID.
272
273 <p><dt><tt>void <b>SciPlotSetForegroundColor</b>(GtkWidget *w, int color)</tt>
274 <dd>Sets the default foreground (axes, labels, legend outline) to the given colour ID.
275 </dl>
276
277 <li><h3><a name="list">Data Manipulation Functions</a></h3>
278 <p>All creation functions return an integer list ID used by subsequent calls.
279 Pass <tt>num=0</tt> and <tt>NULL</tt> arrays to create an empty list and
280 populate it incrementally with <tt>SciPlotListAddFloat</tt> etc.
281 <dl>
282 <p><dt><tt>int <b>SciPlotListCreateFloat</b>(GtkWidget *w, int num, float *xlist, float *ylist, const char *legend)</tt>
283 <dd>Creates a list from float arrays. Initial style: black points (circle) and line (solid).
284
285 <p><dt><tt>int <b>SciPlotListCreateDouble</b>(GtkWidget *w, int num, double *xlist, double *ylist, const char *legend)</tt>
286 <dd>Same, for double arrays.
287
288 <p><dt><tt>int <b>SciPlotListCreateFromData</b>(GtkWidget *w, int num, real *xlist, real *ylist, const char *legend, int pcolor, int pstyle, int lcolor, int lstyle)</tt>
289 <dd>Creates a list from <tt>real</tt> (float) arrays with explicit style.
290
291 <p><dt><tt>void <b>SciPlotListUpdateFloat</b>(GtkWidget *w, int id, int num, float *xlist, float *ylist)</tt>
292 <dd>Replaces the data in list <i>id</i> with new float arrays.
293
294 <p><dt><tt>void <b>SciPlotListUpdateDouble</b>(GtkWidget *w, int id, int num, double *xlist, double *ylist)</tt>
295 <dd>Same, for double arrays.
296
297 <p><dt><tt>void <b>SciPlotListAddFloat</b>(GtkWidget *w, int id, int num, float *xlist, float *ylist)</tt>
298 <dd>Appends float data to list <i>id</i>.
299
300 <p><dt><tt>void <b>SciPlotListAddDouble</b>(GtkWidget *w, int id, int num, double *xlist, double *ylist)</tt>
301 <dd>Same, for double arrays.
302
303 <p><dt><tt>void <b>SciPlotListDelete</b>(GtkWidget *w, int id)</tt>
304 <dd>Removes list <i>id</i> from the widget.
305
306 <p><dt><tt>void <b>SciPlotListSetStyle</b>(GtkWidget *w, int id, int pcolor, int pstyle, int lcolor, int lstyle)</tt>
307 <dd>Sets point colour, point style, line colour, and line style for list <i>id</i>.
308 Pass -1 for any parameter to leave it unchanged.
309
310 <p><dt><tt>void <b>SciPlotListSetMarkerSize</b>(GtkWidget *w, int id, float size)</tt>
311 <dd>Sets the marker size (pixels) for list <i>id</i>.
312 </dl>
313
314 <li><h3><a name="graph">Graph Control Functions</a></h3>
315 <dl>
316 <p><dt><tt>void <b>SciPlotSetXAutoScale</b>(GtkWidget *w)</tt>
317 <dd>(Cartesian.) Restores automatic X-axis scaling from data range.
318
319 <p><dt><tt>void <b>SciPlotSetXUserScale</b>(GtkWidget *w, double min, double max)</tt>
320 <dd>(Cartesian, non-log.) Forces the X axis to display [min, max].
321
322 <p><dt><tt>void <b>SciPlotSetYAutoScale</b>(GtkWidget *w)</tt>
323 <dd>(Cartesian.) Restores automatic Y-axis scaling.
324
325 <p><dt><tt>void <b>SciPlotSetYUserScale</b>(GtkWidget *w, double min, double max)</tt>
326 <dd>(Cartesian, non-log.) Forces the Y axis to display [min, max].
327 </dl>
328
329 <li><h3><a name="output">Hardcopy/Output Functions</a></h3>
330 <dl>
331 <p><dt><tt>gboolean <b>SciPlotPSCreate</b>(GtkWidget *w, const char *filename)</tt>
332 <dd>Writes an EPS file of the current plot. Returns TRUE on success.
333
334 <p><dt><tt>gboolean <b>SciPlotPSCreateColor</b>(GtkWidget *w, const char *filename)</tt>
335 <dd>Same as SciPlotPSCreate (both produce colour output).
336
337 <p><dt><tt>void <b>SciPlotExportData</b>(GtkWidget *w, FILE *fd)</tt>
338 <dd>Writes a tab-separated summary of all list data to the already-open file
339 <i>fd</i>, importable by most graphing tools.
340 </dl>
341 </ul>
342
343 <p><hr><h2><a name="bug">Known Issues</a></h2>
344 <ul>
345 <li>Font fallback follows Pango/fontconfig rules; the requested family may be
346 substituted silently if not installed.
347 <li>PostScript output relies on Cairo's font embedding; complex scripts or
348 unusual fonts may not embed correctly in all viewers.
349 </ul>
350
351 <hr>
352
353 <br> <a href=SciPlot.html>SciPlot</a> :
354 <a href=SciPlotProg.html>Programmer's Reference</a> |
355 <a href=SciPlotDemo.html>Demo Programs</a>
356 <br><hr>Originally by <a href="mailto:[email protected]">Rob McMullen</a>.
357 GTK4 port by <a href="mailto:[email protected]">Barak A. Pearlmutter</a>.
358 Updated: 2 Jun 2026<br></body></html>