NAME

kplot_alloc — allocate plotting context

LIBRARY

library “libkplot”

SYNOPSIS

#include <cairo.h>
#include <kplot.h>

struct kplot *
kplot_alloc(const struct kplotcfg *cfg);

DESCRIPTION

The kplot_alloc function allocates a plotting context for later use by kplot_attach_data(3), kplot_draw(3), and so on. It must be freed with kplot_free(3). The only argument, cfg, is copied: all allocated members (e.g., clrs and Cairo pattern) are re-allocated or referenced, as the case may be, so the caller can free all memory in the meantime. The options provided via the cfg object are as follows:

extrema

A bit-field allowing arbitrary assignment of xy-ranges: EXTREMA_XMIN, EXTREMA_XMAX, EXTREMA_YMIN, and/or EXTREMA_YMAX. This fixates the ranges unconditionally (i.e., no auto-scaling will occur and points or lines drawn outside will be clipped).

extrema_xmin

If EXTREMA_XMIN is set, this value will be used instead of a value computed from the data.

extrema_xmax

See extrema_xmin.

extrema_ymin

See extrema_xmin.

extrema_ymax

See extrema_xmin.

margin

Bitfield of which margins to draw: MARGIN_LEFT, MARGIN_RIGHT, MARGIN_TOP, MARGIN_BOTTOM, or MARGIN_ALL.

marginsz

The width of the margin in user-space Cairo coordinates. These are clamped to be non-negative. The margin is the space between the image boundary and the longest (or tallest) label edge, or if no label is specified on any face, the plot area.

ticlabel

Bitfield of which labels to draw: TICLABEL_LEFT, TICLABEL_RIGHT, TICLABEL_TOP, or TICLABEL_BOTTOM.

ticlabelfont

All font characteristics of the tic labels.

xticlabelpad

Space between horizontal (x-axis) tic labels and the plot area. Specifically, between the edge of the longest label along any face and the plot area.

yticlabelpad

See xticlabelpad.

xticlabelrot

Rotation of horizontal (x-axis) labels (in radians) clamped to 90 degrees. Rotation is clockwise. Note that if this is nonzero, the tic label is aligned under the tic-mark at the top-left part of the field, instead of the middle as is the usual case.

xticlabelfmt

This function may be user-defined for formatting the horizontal x-axis label as a UTF-8 string limited to 128 bytes (including nil terminator). It accepts three arguments: the value to format, the string buffer in which to format, and the size of the buffer. The default is to use snprintf(3) with the %g format string.

yticlabelfmt

See xticlabelfmt.

border

Bitfield of which borders to draw: BORDER_LEFT, BORDER_RIGHT, BORDER_TOP, BORDER_BOTTOM, or BORDER_ALL.

borderline

The configuration of the border line. See kplot_attach_data(3) for an explanation of the line structure.

clrs

Array of colour configurations for the colour palette. If no colours are specified, which is the default, a default palette will be installed. See kplot_attach_data(3) for a description of the colour structure.

clrsz

The number of colours in clrs. Colour indices index into the clrs array modulo this value.

xtics

The number of tics (and thus labels) to draw along the horizontal x-axis. The border condition (one tic) is drawn in the centre.

ytics

See xtics.

tic

Bitfield of which tics to draw: TIC_LEFT_IN, TIC_RIGHT_IN, TIC_TOP_IN, TIC_BOTTOM_IN, TIC_LEFT_OUT, TIC_RIGHT_OUT, TIC_TOP_OUT, or TIC_BOTTOM_OUT.

ticline

The configuration of the tic line. See kplot_attach_data(3) for an explanation of the line structure.

xaxislabel

The label for the x-axis, shown below the bottom x-axis tic labels (if specified).

x2axislabel

The label for the second x-axis, shown above the top x-axis tic labels (if specified).

yaxislabel

See xaxislabel.

y2axislabel

See xaxislabel.

xaxislabelrot

The clockwise rotation of the x-axis label. Note that this will turn around its centre, so no matter the rotation, it will be correctly buffered on both sides.

yaxislabelrot

See xaxislabelrot.

xaxislabelpad

The padding between the top of the x-axis label and the bottom of the x-axis tics (if specified).

yaxislabelpad

See xaxislabelpad.

axislabelfont

All font characteristics for the xaxislabel and yaxislabel.

grid

Bitfield of which grid lines to draw: GRID_X, GRID_Y, or GRID_ALL.

gridline

The configuration of grid lines.

If NULL is passed as a configuration, reasonable defaults are used.

RETURN VALUES

kplot_alloc returns NULL on memory allocation failure.

SEE ALSO

kplot(3), kplot_free(3)