From d405bc913b1d7d23ff12f92f6ef6323d15a4610d Mon Sep 17 00:00:00 2001 From: Jim Evins Date: Sun, 7 Nov 2010 17:35:30 -0500 Subject: [PATCH] Initial documentation for libglbarcode. --- .gitignore | 1 + configure.ac | 1 + docs/Makefile.am | 4 +- docs/libglbarcode/Makefile.am | 73 ++++++ docs/libglbarcode/intro.sgml | 161 +++++++++++++ docs/libglbarcode/libglbarcode-3.0-docs.sgml | 31 +++ .../libglbarcode-3.0-overrides.txt | 0 .../libglbarcode-3.0-sections.txt | 46 ++++ docs/libglbarcode/libglbarcode-3.0.types | 0 .../libglbarcode/tmpl/lgl-barcode-create.sgml | 37 +++ .../tmpl/lgl-barcode-render-to-cairo.sgml | 40 ++++ docs/libglbarcode/tmpl/lgl-barcode-type.sgml | 36 +++ docs/libglbarcode/tmpl/lgl-barcode.sgml | 214 ++++++++++++++++++ .../tmpl/libglbarcode-3.0-unused.sgml | 0 libglbarcode/lgl-barcode-create.c | 24 +- libglbarcode/lgl-barcode-render-to-cairo.c | 29 ++- libglbarcode/lgl-barcode-type.h | 19 +- libglbarcode/lgl-barcode.c | 137 +++++++++-- libglbarcode/lgl-barcode.h | 112 ++++++++- libglbarcode/libglbarcode-3.0.pc.in | 1 + libglbarcode/libglbarcode.h | 3 +- 21 files changed, 930 insertions(+), 39 deletions(-) create mode 100644 docs/libglbarcode/Makefile.am create mode 100644 docs/libglbarcode/intro.sgml create mode 100644 docs/libglbarcode/libglbarcode-3.0-docs.sgml create mode 100644 docs/libglbarcode/libglbarcode-3.0-overrides.txt create mode 100644 docs/libglbarcode/libglbarcode-3.0-sections.txt create mode 100644 docs/libglbarcode/libglbarcode-3.0.types create mode 100644 docs/libglbarcode/tmpl/lgl-barcode-create.sgml create mode 100644 docs/libglbarcode/tmpl/lgl-barcode-render-to-cairo.sgml create mode 100644 docs/libglbarcode/tmpl/lgl-barcode-type.sgml create mode 100644 docs/libglbarcode/tmpl/lgl-barcode.sgml create mode 100644 docs/libglbarcode/tmpl/libglbarcode-3.0-unused.sgml diff --git a/.gitignore b/.gitignore index 84676e3d..07535616 100644 --- a/.gitignore +++ b/.gitignore @@ -43,6 +43,7 @@ glabels-*.tar.gz /xmldocs.make /libglabels/libglabels*.pc +/libglbarcode/libglbarcode*.pc /src/marshal.[ch] /src/stock-pixmaps/stockpixbufs.h diff --git a/configure.ac b/configure.ac index 37b047da..973bcd75 100644 --- a/configure.ac +++ b/configure.ac @@ -338,6 +338,7 @@ po/Makefile.in help/Makefile docs/Makefile docs/libglabels/Makefile +docs/libglbarcode/Makefile glabels.spec ]) AC_OUTPUT diff --git a/docs/Makefile.am b/docs/Makefile.am index 0cb49459..a0be5c8e 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -1,3 +1,5 @@ ## Process this file with automake to produce Makefile.in. -SUBDIRS = libglabels +SUBDIRS = \ + libglabels \ + libglbarcode diff --git a/docs/libglbarcode/Makefile.am b/docs/libglbarcode/Makefile.am new file mode 100644 index 00000000..1bed761a --- /dev/null +++ b/docs/libglbarcode/Makefile.am @@ -0,0 +1,73 @@ +## Process this file with automake to produce Makefile.in + +# We require automake 1.6 at least. +AUTOMAKE_OPTIONS = 1.6 + +# This is a blank Makefile.am for using gtk-doc. +# Copy this to your project's API docs directory and modify the variables to +# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples +# of using the various options. + +# The name of the module, e.g. 'glib'. +DOC_MODULE=libglbarcode-3.0 + +# The top-level SGML file. You can change this if you want to. +DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml + +# The directory containing the source code. Relative to $(srcdir). +# gtk-doc will search all .c & .h files beneath here for inline comments +# documenting the functions and macros. +# e.g. DOC_SOURCE_DIR=../../../gtk +DOC_SOURCE_DIR=../../libglbarcode + +# Extra options to pass to gtkdoc-scangobj. Not normally needed. +SCANGOBJ_OPTIONS= + +# Extra options to supply to gtkdoc-scan. +# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED" +SCAN_OPTIONS= + +# Extra options to supply to gtkdoc-mkdb. +# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml +MKDB_OPTIONS=--sgml-mode --output-format=xml + +# Extra options to supply to gtkdoc-fixref. Not normally needed. +# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html +FIXXREF_OPTIONS= + +# Used for dependencies. The docs will be rebuilt if any of these change. +# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h +# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c +HFILE_GLOB= +CFILE_GLOB= + +# Header files to ignore when scanning. +# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h +IGNORE_HFILES= \ + lgl-barcode-code39.h \ + lgl-barcode-onecode.h \ + lgl-barcode-postnet.h + +# Images to copy into HTML directory. +# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png +HTML_IMAGES= + +# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE). +# e.g. content_files=running.sgml building.sgml changes-2.0.sgml +content_files= \ + intro.sgml + +# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library. +# Only needed if you are using gtkdoc-scangobj to dynamically query widget +# signals and properties. +# e.g. INCLUDES=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS) +# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib) +INCLUDES= +GTKDOC_LIBS= + +# This includes the standard gtk-doc make rules, copied by gtkdocize. +include $(top_srcdir)/gtk-doc.make + +# Other files to distribute +# e.g. EXTRA_DIST += version.xml.in +EXTRA_DIST += diff --git a/docs/libglbarcode/intro.sgml b/docs/libglbarcode/intro.sgml new file mode 100644 index 00000000..7d9724d6 --- /dev/null +++ b/docs/libglbarcode/intro.sgml @@ -0,0 +1,161 @@ + + +Introduction +3 + + LIBGLBARCODE-3.0 Library + + + + +Introduction + +Introduction to libglbarcode library + + + + + +Overview + + +Libglbarcode provides the core barcode functionality for glabels. It provides +an intermediate barcode format, a small set of built-in barcode back-ends, and a cairo renderer. While +libglbarcode does not currently include a large set of built-in barcode back-ends or renderers, its +simple architecture would easily support extending its functionality beyond the needs of +glabels. + + + + + + +Basic Usage + + + +#include <libglbarcode/lgl-barcode-create.h> +#include <libglbarcode/lgl-barcode-render-to-cairo.h> + +void +example (gchar *data, + cairo_t *cr) +{ + glBarcode *bc; + + bc = lgl_barcode_create (LGL_BARCODE_TYPE_CODE39, TRUE, FALSE, 0, 0, data); + + /* Render to cairo context. Assume context has appropriate scale and translation. + * Scale should be such that world units are points (1 point = 1/72 inch) and that + * positive y values go downward. + */ + lgl_barcode_render_to_cairo (bc, cr); + + lgl_free (bc); +} + + + + + + + + +Writing Renderers + + +The lglBarcode structure is independent of +barcode type, and consists of a simple list of drawing primitives. +A renderer simply traverses this list translating these primitives into native +drawing commands for its target format or device. +All renderers will follow this simple pattern as illustrated in the example +below. + + + + +#include <libglbarcode/lgl-barcode.h> +#include <xxx.h> + +void +lgl_barcode_render_to_xxx (const lglBarcode *bc) +{ + GList *p; + + lglBarcodeShape *shape; + lglBarcodeShapeLine *line; + lglBarcodeShapeBox *box; + lglBarcodeShapeChar *bchar; + lglBarcodeShapeString *bstring; + lglBarcodeShapeRing *ring; + lglBarcodeShapeHexagon *hexagon; + + + for (p = bc->shapes; p != NULL; p = p->next) { + + shape = (lglBarcodeShape *)p->data; + + switch (shape->type) + { + + case LGL_BARCODE_SHAPE_LINE: + line = (lglBarcodeShapeLine *) shape; + + xxx_plot_line (line->x, line->y, + line->x, line->y + line->length, + line->width ); + break; + + case LGL_BARCODE_SHAPE_BOX: + box = (lglBarcodeShapeBox *) shape; + + xxx_plot_rectangle (box->x, box->y, + box->width, box->height); + break; + + case LGL_BARCODE_SHAPE_CHAR: + bchar = (lglBarcodeShapeChar *) shape; + + ... + xxx_plot_char (...); + break; + + case LGL_BARCODE_SHAPE_STRING: + bstring = (lglBarcodeShapeString *) shape; + + ... + xxx_plot_string (...); + break; + + case LGL_BARCODE_SHAPE_RING: + ring = (lglBarcodeShapeRing *) shape; + + ... + xxx_plot_circle (...); + break; + + case LGL_BARCODE_SHAPE_HEXAGON: + hexagon = (lglBarcodeShapeHexagon *) shape; + + ... + xxx_plot_polygon (...); + break; + + default: + g_assert_not_reached (); + break; + + } + + } + +} + + + + + + + + + diff --git a/docs/libglbarcode/libglbarcode-3.0-docs.sgml b/docs/libglbarcode/libglbarcode-3.0-docs.sgml new file mode 100644 index 00000000..d04ced26 --- /dev/null +++ b/docs/libglbarcode/libglbarcode-3.0-docs.sgml @@ -0,0 +1,31 @@ + + + +]> + + + + LibGlbarcode 3.0 Reference Manual + + + + LibGlbarcode Overview + + &libglbarcode-intro; + + + + + API Reference + + + + + + + + + diff --git a/docs/libglbarcode/libglbarcode-3.0-overrides.txt b/docs/libglbarcode/libglbarcode-3.0-overrides.txt new file mode 100644 index 00000000..e69de29b diff --git a/docs/libglbarcode/libglbarcode-3.0-sections.txt b/docs/libglbarcode/libglbarcode-3.0-sections.txt new file mode 100644 index 00000000..0eb153ca --- /dev/null +++ b/docs/libglbarcode/libglbarcode-3.0-sections.txt @@ -0,0 +1,46 @@ +
+lgl-barcode +libglbarcode/lgl-barcode.h + +lglBarcode + +lgl_barcode_new +lgl_barcode_free + +lglBarcodeShapeType +lglBarcodeShape +lglBarcodeShapeAny +lglBarcodeShapeLine +lglBarcodeShapeBox +lglBarcodeShapeChar +lglBarcodeShapeString +lglBarcodeShapeRing +lglBarcodeShapeHexagon + +lgl_barcode_add_line +lgl_barcode_add_box +lgl_barcode_add_char +lgl_barcode_add_string +lgl_barcode_add_ring +lgl_barcode_add_hexagon +
+ +
+lgl-barcode-create +libglbarcode/lgl-barcode-create.h +lgl_barcode_create +
+ +
+lgl-barcode-render-to-cairo +libglbarcode/lgl-barcode-render-to-cairo.h +lgl_barcode_render_to_cairo +lgl_barcode_render_to_cairo_path +
+ +
+lgl-barcode-type +libglbarcode/lgl-barcode-type.h +lglBarcodeType +
+ diff --git a/docs/libglbarcode/libglbarcode-3.0.types b/docs/libglbarcode/libglbarcode-3.0.types new file mode 100644 index 00000000..e69de29b diff --git a/docs/libglbarcode/tmpl/lgl-barcode-create.sgml b/docs/libglbarcode/tmpl/lgl-barcode-create.sgml new file mode 100644 index 00000000..7d1e9e73 --- /dev/null +++ b/docs/libglbarcode/tmpl/lgl-barcode-create.sgml @@ -0,0 +1,37 @@ + +Barcode Factory + + +Basic end-user barcode creation API + + + +This section describes a simple API to select and create #glBarcode structures using a built-in +barcode backend. + + + + + + + + + + + + + + + + + + +@type: +@text_flag: +@checksum_flag: +@w: +@h: +@data: +@Returns: + + diff --git a/docs/libglbarcode/tmpl/lgl-barcode-render-to-cairo.sgml b/docs/libglbarcode/tmpl/lgl-barcode-render-to-cairo.sgml new file mode 100644 index 00000000..47938282 --- /dev/null +++ b/docs/libglbarcode/tmpl/lgl-barcode-render-to-cairo.sgml @@ -0,0 +1,40 @@ + +Cairo Renderer + + +Render barcode to cairo context + + + +This section describes the cairo barcode renderer. + + + + + + + + + + + + + + + + + + +@bc: +@cr: + + + + + + + +@bc: +@cr: + + diff --git a/docs/libglbarcode/tmpl/lgl-barcode-type.sgml b/docs/libglbarcode/tmpl/lgl-barcode-type.sgml new file mode 100644 index 00000000..c7c1d6f6 --- /dev/null +++ b/docs/libglbarcode/tmpl/lgl-barcode-type.sgml @@ -0,0 +1,36 @@ + +Barcode Types + + +Enumeration of supported barcode types + + + +This section describes an enumeration for selecting one of the barcode types supported by libglbarcode. + + + + + + + + + + + + + + + +This enumeration is used to select a built-in barcode type. The currently supported barcode types are + + +@LGL_BARCODE_TYPE_POSTNET: USPS Postnet Barcode (5, 9, or 11 digits) +@LGL_BARCODE_TYPE_POSTNET_5: USPS Postnet Barcode (5 digits) +@LGL_BARCODE_TYPE_POSTNET_9: USPS Postnet Barcode (9 digits) +@LGL_BARCODE_TYPE_POSTNET_11: USPS Postnet Barcode (11 digits) +@LGL_BARCODE_TYPE_CEPNET: Brazilian Postal Code +@LGL_BARCODE_TYPE_ONECODE: USPS Intelligent Mail Barcode +@LGL_BARCODE_TYPE_CODE39: Code 39 +@LGL_BARCODE_TYPE_CODE39_EXT: Extended Code 39 (Supports full ASCII character set) + diff --git a/docs/libglbarcode/tmpl/lgl-barcode.sgml b/docs/libglbarcode/tmpl/lgl-barcode.sgml new file mode 100644 index 00000000..0d10991b --- /dev/null +++ b/docs/libglbarcode/tmpl/lgl-barcode.sgml @@ -0,0 +1,214 @@ + +lglBarcode + + +Barcode structure + + + +This section describes the #lglBarcode structure and the #lglBarcodeShape family of simple drawing primitives. +These structures form the basic intermediate barcode representation used by libglbarcode. +The section also defines a set of functions for constructing an #lglBarcode structure and populating it with drawing primitives. + + + + + + + + + + + + + + + + + + +@width: +@height: +@shapes: + + + + + + +@void: +@Returns: + + + + + + + +@bc: + + + + + + + +@LGL_BARCODE_SHAPE_LINE: +@LGL_BARCODE_SHAPE_BOX: +@LGL_BARCODE_SHAPE_CHAR: +@LGL_BARCODE_SHAPE_STRING: +@LGL_BARCODE_SHAPE_RING: +@LGL_BARCODE_SHAPE_HEXAGON: + + + + + + + + + + + + +@type: +@x: +@y: + + + + + + +@type: +@x: +@y: +@length: +@width: + + + + + + +@type: +@x: +@y: +@width: +@height: + + + + + + +@type: +@x: +@y: +@fsize: +@c: + + + + + + +@type: +@x: +@y: +@fsize: +@string: + + + + + + +@type: +@x: +@y: +@radius: +@line_width: + + + + + + +@type: +@x: +@y: +@height: + + + + + + +@bc: +@x: +@y: +@length: +@width: + + + + + + + +@bc: +@x: +@y: +@width: +@height: + + + + + + + +@bc: +@x: +@y: +@fsize: +@c: + + + + + + + +@bc: +@x: +@y: +@fsize: +@string: +@length: + + + + + + + +@bc: +@x: +@y: +@radius: +@line_width: + + + + + + + +@bc: +@x: +@y: +@height: + + diff --git a/docs/libglbarcode/tmpl/libglbarcode-3.0-unused.sgml b/docs/libglbarcode/tmpl/libglbarcode-3.0-unused.sgml new file mode 100644 index 00000000..e69de29b diff --git a/libglbarcode/lgl-barcode-create.c b/libglbarcode/lgl-barcode-create.c index fe2dadcd..f149c972 100644 --- a/libglbarcode/lgl-barcode-create.c +++ b/libglbarcode/lgl-barcode-create.c @@ -68,8 +68,28 @@ BarcodeNewFunc create_func[LGL_BARCODE_N_TYPES] = { /****************************************************************************/ -/* Lookup barcode type and create appropriate barcode. */ -/****************************************************************************/ +/** + * lgl_barcode_create: + * @type: Barcode type selection (#lglBarcodeType) + * @text_flag: %TRUE to show text, if supported by barcode type + * @checksum_flag: %TRUE to include checksum, if supported or optional for barcode type + * @w: Suggested width of barcode + * @h: Suggested height of barcode + * @data: Data to encode into barcode + * + * Create a new barcode structure, encoding @data with selected barcode type and + * characteristics. + * + * Barcode dimensions (@w and @h) are in points ( 1 point = 1/72 inch ). + * If either @w or @h are zero, the barcode will be rendered in a nominal size + * appropriate for the barcode type and data. The actual size of the resulting + * barcode may also be limited by required tolerances of line sizes and spacing + * for the given barcode type. + * + * + * Returns: A newly allocated #lglBarcode structure. Use lgl_barcode_free() to + * free it. + */ lglBarcode * lgl_barcode_create (lglBarcodeType type, gboolean text_flag, diff --git a/libglbarcode/lgl-barcode-render-to-cairo.c b/libglbarcode/lgl-barcode-render-to-cairo.c index 1dd1700f..79a22225 100644 --- a/libglbarcode/lgl-barcode-render-to-cairo.c +++ b/libglbarcode/lgl-barcode-render-to-cairo.c @@ -51,8 +51,18 @@ /****************************************************************************/ -/* Render barcode to cairo context. */ -/****************************************************************************/ +/** + * lgl_barcode_render_to_cairo: + * @bc: An #lglBarcode structure + * @cr: A #cairo_t context + * + * Render barcode to cairo context. Context should be prepared with desired + * translation and appropriate scale. Context should be translated such that + * the origin is at the desired location of the upper left hand corner of the + * barcode bounding box. Context should be scaled such that all dimensions + * are in points ( 1 point = 1/72 inch ) and that positive y coordinates + * go down the surface. + */ void lgl_barcode_render_to_cairo (const lglBarcode *bc, cairo_t *cr) @@ -185,8 +195,19 @@ lgl_barcode_render_to_cairo (const lglBarcode *bc, /****************************************************************************/ -/* Render barcode to cairo context (creating a path only). */ -/****************************************************************************/ +/** + * lgl_barcode_render_to_cairo_path: + * @bc: An #lglBarcode structure + * @cr: A #cairo_t context + * + * Render barcode to cairo context, but only create a path to be filled or + * tested against. Context should be prepared with desired + * translation and appropriate scale. Context should be translated such that + * the origin is at the desired location of the upper left hand corner of the + * barcode bounding box. Context should be scaled such that all dimensions + * are in points ( 1 point = 1/72 inch ) and that positive y coordinates + * go down the surface. + */ void lgl_barcode_render_to_cairo_path (const lglBarcode *bc, cairo_t *cr) diff --git a/libglbarcode/lgl-barcode-type.h b/libglbarcode/lgl-barcode-type.h index 43634d7a..9fc0b9f0 100644 --- a/libglbarcode/lgl-barcode-type.h +++ b/libglbarcode/lgl-barcode-type.h @@ -28,15 +28,18 @@ G_BEGIN_DECLS typedef enum { - LGL_BARCODE_TYPE_POSTNET, - LGL_BARCODE_TYPE_POSTNET_5, - LGL_BARCODE_TYPE_POSTNET_9, - LGL_BARCODE_TYPE_POSTNET_11, - LGL_BARCODE_TYPE_CEPNET, - LGL_BARCODE_TYPE_ONECODE, - LGL_BARCODE_TYPE_CODE39, - LGL_BARCODE_TYPE_CODE39_EXT, + LGL_BARCODE_TYPE_POSTNET, /* USPS Postnet Barcode (5, 9, or 11 digits) */ + LGL_BARCODE_TYPE_POSTNET_5, /* USPS Postnet Barcode (5 digits) */ + LGL_BARCODE_TYPE_POSTNET_9, /* USPS Postnet Barcode (9 digits) */ + LGL_BARCODE_TYPE_POSTNET_11, /* USPS Postnet Barcode (11 digits) */ + LGL_BARCODE_TYPE_CEPNET, /* Brazilian Postal Code */ + LGL_BARCODE_TYPE_ONECODE, /* USPS Intelligent Mail Barcode */ + + LGL_BARCODE_TYPE_CODE39, /* Code 39 */ + LGL_BARCODE_TYPE_CODE39_EXT, /* Extended Code 39 (Supports full ASCII character set) */ + + /*< private >*/ LGL_BARCODE_N_TYPES } lglBarcodeType; diff --git a/libglbarcode/lgl-barcode.c b/libglbarcode/lgl-barcode.c index 25409d82..ab2c636a 100644 --- a/libglbarcode/lgl-barcode.c +++ b/libglbarcode/lgl-barcode.c @@ -49,8 +49,23 @@ static void lgl_barcode_shape_free (lglBarcodeShape *shape); /*****************************************************************************/ -/* Allocate new empty lglBarcode structure. */ -/*****************************************************************************/ +/** + * lgl_barcode_new: + * + * Allocate a new #lglBarcode structure. + * + * This function allocates a new #lglBarcode structure. + * + * + * This function is intended to be used internally by barcode implementations. + * Typically an end-user would use lgl_barcode_create() instead. + * + * + * + * Returns: A newly allocated #lglBarcode structure. Use lgl_barcode_free() to + * free it. + * + */ lglBarcode * lgl_barcode_new (void) { @@ -59,8 +74,13 @@ lgl_barcode_new (void) /*****************************************************************************/ -/* Free previously created barcode. */ -/*****************************************************************************/ +/** + * lgl_barcode_free: + * @bc: The #lglBarcode structure to free + * + * Free a previously allocated #lglBarcode structure. + * + */ void lgl_barcode_free (lglBarcode *bc) { @@ -82,8 +102,22 @@ lgl_barcode_free (lglBarcode *bc) /*****************************************************************************/ -/* Add a line. */ -/*****************************************************************************/ +/** + * lgl_barcode_add_line: + * @bc: An #lglBarcode structure + * @x: x coordinate of top of line + * @y: y coordinate of top of line + * @length: Length of line + * @width: Width of line + * + * Add a vertical line to barcode. Coordinates are relative to top left corner + * of barcode. All units are in points ( 1 point = 1/72 inch ). + * + * + * This function is intended to be used internally by barcode implementations. + * + * + */ void lgl_barcode_add_line (lglBarcode *bc, gdouble x, @@ -104,8 +138,22 @@ lgl_barcode_add_line (lglBarcode *bc, /*****************************************************************************/ -/* Add box. */ -/*****************************************************************************/ +/** + * lgl_barcode_add_box: + * @bc: An #lglBarcode structure + * @x: x coordinate of top left corner of box + * @y: y coordinate of top left corner of box + * @width: Width of box + * @height: Height of box + * + * Add a box to barcode. Coordinates are relative to top left corner + * of barcode. All units are in points ( 1 point = 1/72 inch ). + * + * + * This function is intended to be used internally by barcode implementations. + * + * + */ void lgl_barcode_add_box (lglBarcode *bc, gdouble x, @@ -126,8 +174,22 @@ lgl_barcode_add_box (lglBarcode *bc, /*****************************************************************************/ -/* Add character. */ -/*****************************************************************************/ +/** + * lgl_barcode_add_char: + * @bc: An #lglBarcode structure + * @x: x coordinate of left baseline of character + * @y: y coordinate of left baseline of character + * @fsize: Font size + * @c: Character to add + * + * Add an ASCII character to barcode. Coordinates are relative to top left corner + * of barcode. All units are in points ( 1 point = 1/72 inch ). + * + * + * This function is intended to be used internally by barcode implementations. + * + * + */ void lgl_barcode_add_char (lglBarcode *bc, gdouble x, @@ -148,8 +210,23 @@ lgl_barcode_add_char (lglBarcode *bc, /*****************************************************************************/ -/* Add string. */ -/*****************************************************************************/ +/** + * lgl_barcode_add_string: + * @bc: An #lglBarcode structure + * @x: x coordinate of horizontal center of baseline of string + * @y: y coordinate of horizontal center of baseline of string + * @fsize: Font size + * @string: String to add + * @length: Number of bytes in string + * + * Add a character string to barcode. Coordinates are relative to top left corner + * of barcode. All units are in points ( 1 point = 1/72 inch ). + * + * + * This function is intended to be used internally by barcode implementations. + * + * + */ void lgl_barcode_add_string (lglBarcode *bc, gdouble x, @@ -170,8 +247,22 @@ lgl_barcode_add_string (lglBarcode *bc, } /*****************************************************************************/ -/* Add ring. */ -/*****************************************************************************/ +/** + * lgl_barcode_add_ring: + * @bc: An #lglBarcode structure + * @x: x coordinate of center of circle + * @y: y coordinate of center of circle + * @radius: Radius of ring (center of line) + * @line_width: Width of line + * + * Add a ring to barcode. Coordinates are relative to top left corner + * of barcode. All units are in points ( 1 point = 1/72 inch ). + * + * + * This function is intended to be used internally by barcode implementations. + * + * + */ void lgl_barcode_add_ring (lglBarcode *bc, gdouble x, @@ -191,8 +282,22 @@ lgl_barcode_add_ring (lglBarcode *bc, } /*****************************************************************************/ -/* Add hexagon. */ -/*****************************************************************************/ +/** + * lgl_barcode_add_hexagon: + * @bc: An #lglBarcode structure + * @x: x coordinate of top point of hexagon + * @y: y coordinate of top point of hexagon + * @height: Height of hexagon + * + * Add a regular hexagon (oriented with vertexes at top and bottom) to barcode. + * Coordinates are relative to top left corner of barcode. All units are in + * points ( 1 point = 1/72 inch ). + * + * + * This function is intended to be used internally by barcode implementations. + * + * + */ void lgl_barcode_add_hexagon (lglBarcode *bc, gdouble x, diff --git a/libglbarcode/lgl-barcode.h b/libglbarcode/lgl-barcode.h index f7f9a072..bcbfbfd6 100644 --- a/libglbarcode/lgl-barcode.h +++ b/libglbarcode/lgl-barcode.h @@ -30,6 +30,19 @@ G_BEGIN_DECLS /* Barcode Intermediate Format. */ /********************************/ +/** + * lglBarcode: + * @width: Width of barcode bounding box (points) + * @height: Height of barcode bounding box (points) + * @shapes: List of #lglBarcodeShape drawing primitives + * + * This structure contains the libglbarcode intermediate barcode format. This + * structure contains a simple vectorized representation of the barcode. This + * vectorized representation is easy to interpret by a rendering backend for + * either vector or raster formats. A simple API is provided for constructing + * barcodes in this format. + * + */ typedef struct { gdouble width; @@ -97,6 +110,7 @@ typedef enum { LGL_BARCODE_SHAPE_HEXAGON, } lglBarcodeShapeType; + typedef struct { /* Begin Common Fields */ @@ -107,8 +121,18 @@ typedef struct { } lglBarcodeShapeAny; -/* + +/** * lglBarcodeShapeLine: + * @type: Always %LGL_BARCODE_SHAPE_LINE + * @x: x coordinate of top of line + * @y: y coordinate of top of line + * @length: Length of line + * @width: Width of line + * + * A vertical line drawing primitive. + * + * * * @ = origin (x,y) from top left corner of barcode * @@ -122,6 +146,10 @@ typedef struct { * | | * +-----+ * width + * + * + * + * All units are in points ( 1 point = 1/72 inch ). */ typedef struct { @@ -136,8 +164,18 @@ typedef struct { } lglBarcodeShapeLine; -/* + +/** * lglBarcodeShapeBox: + * @type: Always %LGL_BARCODE_SHAPE_BOX + * @x: x coordinate of top left corner of box + * @y: y coordinate of top left corner of box + * @width: Width of box + * @height: Height of box + * + * A solid box drawing primitive. + * + * * * @ = origin (x,y) from top left corner of barcode * @@ -151,6 +189,10 @@ typedef struct { * | | * +---------+ * width + * + * + * + * All units are in points ( 1 point = 1/72 inch ). */ typedef struct { @@ -165,8 +207,18 @@ typedef struct { } lglBarcodeShapeBox; -/* + +/** * lglBarcodeShapeChar: + * @type: Always %LGL_BARCODE_SHAPE_CHAR + * @x: x coordinate of left baseline of character + * @y: y coordinate of left baseline of character + * @fsize: Font size + * @c: Character to add + * + * An single byte character drawing primitive. + * + * * * @ = origin (x,y) from top left corner of barcode * @@ -179,6 +231,10 @@ typedef struct { * /__/ \__\ | * v * @ ---------------------- + * + * + * + * All units are in points ( 1 point = 1/72 inch ). */ typedef struct { @@ -193,8 +249,19 @@ typedef struct { } lglBarcodeShapeChar; -/* + +/** * lglBarcodeShapeString: + * @type: Always %LGL_BARCODE_SHAPE_STRING + * @x: x coordinate of horizontal center of baseline of string + * @y: y coordinate of horizontal center of baseline of string + * @fsize: Font size + * @string: String to add + * @length: Number of bytes in string + * + * A character string drawing primitive. + * + * * * @ = origin (x,y) from top left corner of barcode * @@ -208,6 +275,10 @@ typedef struct { * v * @ ------------------ * x = horizontal center + * + * + * + * All units are in points ( 1 point = 1/72 inch ). */ typedef struct { @@ -222,8 +293,18 @@ typedef struct { } lglBarcodeShapeString; -/* + +/** * lglBarcodeShapeRing: + * @type: Always %LGL_BARCODE_SHAPE_RING + * @x: x coordinate of center of circle + * @y: y coordinate of center of circle + * @radius: Radius of ring (center of line) + * @line_width: Width of line + * + * A ring (an open circle) drawing primitive. + * + * * * @ = origin (x,y) is centre of circle * @@ -237,6 +318,10 @@ typedef struct { * \ `.____.' / | radius * `._ ...._.'.......| * `-....-' + * + * + * + * All units are in points ( 1 point = 1/72 inch ). */ typedef struct { @@ -252,8 +337,17 @@ typedef struct { } lglBarcodeShapeRing; -/* - * lglBarcodeShapeHexagon; + +/** + * lglBarcodeShapeHexagon: + * @type: Always %LGL_BARCODE_SHAPE_HEXAGON + * @x: x coordinate of top point of hexagon + * @y: y coordinate of top point of hexagon + * @height: Height of hexagon + * + * A solid regular hexagon (oriented with vertexes at top and bottom) drawing primitive. + * + * * * @ = origin (x,y) is top of hexagon * @@ -272,6 +366,9 @@ typedef struct { * "-_ _-" v * " ------------------ * + * + * + * All units are in points ( 1 point = 1/72 inch ). */ typedef struct { @@ -286,6 +383,7 @@ typedef struct { } lglBarcodeShapeHexagon; + typedef union { lglBarcodeShapeType type; diff --git a/libglbarcode/libglbarcode-3.0.pc.in b/libglbarcode/libglbarcode-3.0.pc.in index bdcbf6d4..325eff26 100644 --- a/libglbarcode/libglbarcode-3.0.pc.in +++ b/libglbarcode/libglbarcode-3.0.pc.in @@ -8,5 +8,6 @@ Description: GLabels Built-In Barcode Library Requires: glib-2.0 cairo pango Version: @VERSION@ Libs: -L${libdir} -lglbarcode-3.0 +Libs.private: -lm Cflags: -I${includedir}/@LIBGLBARCODE_BRANCH@ diff --git a/libglbarcode/libglbarcode.h b/libglbarcode/libglbarcode.h index bad41ee7..e0ee61f1 100644 --- a/libglbarcode/libglbarcode.h +++ b/libglbarcode/libglbarcode.h @@ -28,8 +28,9 @@ #include -#include +#include #include +#include #endif /* __LIBGLBARCODE_H__ */ -- 2.39.5