src/output/cairo.h

   1 /* PSPP - a program for statistical analysis.
   2    Copyright (C) 2009, 2010 Free Software Foundation, Inc.
   3
   4    This program is free software: you can redistribute it and/or modify
   5    it under the terms of the GNU General Public License as published by
   6    the Free Software Foundation, either version 3 of the License, or
   7    (at your option) any later version.
   8
   9    This program is distributed in the hope that it will be useful,
  10    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12    GNU General Public License for more details.
  13
  14    You should have received a copy of the GNU General Public License
  15    along with this program.  If not, see <http://www.gnu.org/licenses/>. */
  16
  17 #ifndef OUTPUT_CAIRO_H
  18 #define OUTPUT_CAIRO_H 1
  19
  20 #include <stdbool.h>
  21
  22 #ifdef HAVE_CAIRO
  23
  24 #include <cairo/cairo.h>
  25
  26 struct chart_item;
  27 struct output_item;
  28 struct string_map;
  29
  30 /* Creating and destroying Cairo output drivers. */
  31 struct xr_driver *xr_driver_create (cairo_t *, struct string_map *options);
  32 void xr_driver_destroy (struct xr_driver *);
  33
  34 /* Functions for rendering a single output item to a Cairo context.
  35    Output items are never broken across multiple pages.
  36    Used by PSPPIRE to render in the GUI. */
  37 struct xr_rendering *xr_rendering_create (struct xr_driver *,
  38                                           const struct output_item *,
  39                                           cairo_t *);
  40 void xr_rendering_measure (struct xr_rendering *, int *w, int *h);
  41 void xr_rendering_draw (struct xr_rendering *, cairo_t *,
  42                         int x, int y, int w, int h);
  43
  44 /* Functions for rendering a series of output items to a series of Cairo
  45    contexts, with pagination, possibly including headers.
  46
  47    The intended usage pattern is this:
  48
  49      * Create an xr_driver with xr_driver_create().  The cairo_t passed in must
  50        accurately reflect the properties of the output (e.g. for the purpose of
  51        page size and font selection) but need not be used for rendering.
  52
  53      * Call xr_driver_next_page() to set up the first real output page's
  54        cairo_t.  (You can skip this step if the cairo_t passed to
  55        xr_driver_create() can be used.)
  56
  57      * Then, for each output_item:
  58
  59        - Pass the output item to xr_driver_output_item().  As much output as
  60          fits will be rendered on the current page.
  61
  62        - Then, as long as xr_driver_need_new_page() returns true, obtain a new
  63          page for rendering and pass it to xr_driver_next_page().  As much
  64          output as fits on the new page will be rendered on it.
  65
  66      * When you're done, destroy the output driver with xr_driver_destroy().
  67
  68    These functions may also be used for counting pages without actually
  69    rendering output.  Follow the same steps, except pass NULL as the cairo_t to
  70    xr_driver_next_page().  (But xr_driver_create() still needs a valid cairo_t
  71    for page setup.)
  72
  73    (If the cairo_t that you pass to xr_driver_create() won't remain valid, be
  74    sure to clear it out one way or another before calling xr_driver_destroy(),
  75    so that xr_driver_destroy() won't destroy it itself.)
  76 */
  77 void xr_driver_next_page (struct xr_driver *, cairo_t *);
  78 void xr_driver_output_item (struct xr_driver *, const struct output_item *);
  79 bool xr_driver_need_new_page (const struct xr_driver *);
  80 bool xr_driver_is_page_blank (const struct xr_driver *);
  81
  82 /* Render charts with Cairo. */
  83 char *xr_draw_png_chart (const struct chart_item *,
  84                          const char *file_name_template, int number);
  85
  86 #endif  /* HAVE_CAIRO */
  87
  88 #endif /* output/cairo.h */