src/helper/units.h

   1 #ifndef __SP_UNIT_H__
   2 #define __SP_UNIT_H__
   3
   4 /*
   5  * SPUnit
   6  *
   7  * Ported from libgnomeprint
   8  *
   9  * Authors:
  10  *   Dirk Luetjens <dirk@luedi.oche.de>
  11  *   Yves Arrouye <Yves.Arrouye@marin.fdn.fr>
  12  *   Lauris Kaplinski <lauris@ximian.com>
  13  *
  14  * Copyright 1999-2001 Ximian, Inc. and authors
  15  *
  16  */
  17
  18 #include <glib/gmessages.h>
  19 #include <glib/gslist.h>
  20 #include <glib/gtypes.h>
  21 #include "sp-metric.h"
  22
  23
  24 /*
  25  * Units and conversion methods used by libgnomeprint.
  26  *
  27  * You need those for certain config keys (like paper size), if you are
  28  * interested in using these (look at gnome-print-config.h for discussion,
  29  * why you may NOT be interested in paper size).
  30  *
  31  * Unit bases define set of mutually unrelated measuring systems (numbers,
  32  * paper, screen and dimesionless user coordinates). Still, you can convert
  33  * between those, specifying scaling factors explicitly.
  34  *
  35  * Paper (i.e. output) coordinates are taken as absolute real world units.
  36  * It has some justification, because screen unit (pixel) size changes,
  37  * if you change screen resolution, while you cannot change output on paper
  38  * as easily (unless you have thermally contracting paper, of course).
  39  *
  40  */
  41
  42 struct SPUnit;
  43 struct SPDistance;
  44
  45 /*
  46  * The base linear ("absolute") unit is 1/72th of an inch, i.e. the base unit of postscript.
  47  */
  48
  49 /*
  50  * Unit bases
  51  */
  52 enum SPUnitBase {
  53         SP_UNIT_DIMENSIONLESS = (1 << 0), /* For percentages and like */
  54         SP_UNIT_ABSOLUTE = (1 << 1), /* Real world distances - i.e. mm, cm... */
  55         SP_UNIT_DEVICE = (1 << 2), /* Pixels in the SVG/CSS sense. */
  56         SP_UNIT_VOLATILE = (1 << 3) /* em and ex */
  57 };
  58
  59 /*
  60  * Units: indexes into sp_units.
  61  */
  62 enum SPUnitId {
  63         SP_UNIT_SCALE,  // 1.0 == 100%
  64         SP_UNIT_PT,     // Postscript points: exactly 72 per inch
  65         SP_UNIT_PC,     // Pica; there are 12 points per pica
  66         SP_UNIT_PX,     // "Pixels" in the CSS sense; though Inkscape assumes a constant 90 per inch.
  67         SP_UNIT_PERCENT,  /* Note: In Inkscape this often means "relative to current value" (for
  68                              users to edit a value), rather than the SVG/CSS use of percentages. */
  69         SP_UNIT_MM,     // millimetres
  70         SP_UNIT_CM,     // centimetres
  71         SP_UNIT_M,      // metres
  72         SP_UNIT_IN,     // inches
  73         SP_UNIT_FT,     // foot
  74         SP_UNIT_EM,     // font-size of relevant font
  75         SP_UNIT_EX,     // x-height of relevant font
  76         sp_max_unit_id = SP_UNIT_EX     // For bounds-checking in sp_unit_get_by_id.
  77 };
  78
  79 /*
  80  * Notice, that for correct menus etc. you have to use
  81  * ngettext method family yourself. For that reason we
  82  * do not provide translations in unit names.
  83  * I also do not know, whether to allow user-created units,
  84  * because this would certainly confuse textdomain.
  85  */
  86
  87 struct SPUnit {
  88         SPUnitId unit_id; /* used as sanity check */
  89         SPUnitBase base;
  90         gdouble unittobase; /* how many base units in this unit */
  91         SPMetric metric; // the corresponding SPMetric from sp-metrics.h
  92         guint svg_unit; // the corresponding SVGLengthUnit
  93
  94         /* When using, you must call "gettext" on them so they're translated */
  95         gchar const *name;
  96         gchar const *abbr;
  97         gchar const *plural;
  98         gchar const *abbr_plural;
  99 };
 100
 101 const SPUnit *sp_unit_get_by_abbreviation (const gchar *abbreviation);
 102 /* When using, you must call "gettext" on them so they're translated */
 103 const gchar *sp_unit_get_abbreviation (const SPUnit *unit);
 104 gchar const *sp_unit_get_plural (SPUnit const *unit);
 105
 106 SPMetric sp_unit_get_metric(SPUnit const *unit);
 107 guint sp_unit_get_svg_unit(SPUnit const *unit);
 108
 109 extern SPUnit const sp_units[];
 110
 111 inline SPUnit const &
 112 sp_unit_get_by_id(SPUnitId const id)
 113 {
 114         /* inline because the compiler should optimize away the g_return_val_if_fail test in the
 115            usual case that the argument value is known at compile-time, leaving just
 116            "return sp_units[constant]". */
 117         unsigned const ix = unsigned(id);
 118         g_return_val_if_fail(ix <= sp_max_unit_id, sp_units[SP_UNIT_PX]);
 119         return sp_units[ix];
 120 }
 121
 122 #define SP_PS_UNIT (&sp_unit_get_by_id(SP_UNIT_PT))
 123
 124
 125 /** Used solely by units-test.cpp. */
 126 bool sp_units_table_sane();
 127
 128 #define SP_UNITS_ALL (SP_UNIT_DIMENSIONLESS | SP_UNIT_ABSOLUTE | SP_UNIT_DEVICE | SP_UNIT_VOLATILE)
 129
 130 GSList *sp_unit_get_list (guint bases);
 131 void sp_unit_free_list (GSList *units);
 132
 133 /* These are pure utility */
 134 /* Return TRUE if conversion is possible, FALSE if unit bases differ */
 135 gboolean sp_convert_distance (gdouble *distance, const SPUnit *from, const SPUnit *to);
 136
 137 /* If either one is NULL, transconverting to/from that base fails */
 138 /* Generic conversion between volatile units would be useless anyways */
 139 gdouble sp_convert_distance_full(gdouble const from_dist, SPUnit const &from, SPUnit const &to);
 140
 141 /* Some more convenience */
 142 gdouble sp_units_get_pixels(gdouble const units, SPUnit const &unit);
 143 gdouble sp_pixels_get_units(gdouble const pixels, SPUnit const &unit);
 144
 145 double angle_to_compass(double angle);
 146 double angle_from_compass(double angle);
 147
 148 #endif