[glabels] Initial documentation for libglbarcode.
- From: Jim Evins <jimevins src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [glabels] Initial documentation for libglbarcode.
- Date: Sun, 7 Nov 2010 22:36:13 +0000 (UTC)
commit d405bc913b1d7d23ff12f92f6ef6323d15a4610d
Author: Jim Evins <evins snaught com>
Date: Sun Nov 7 17:35:30 2010 -0500
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 +++
docs/libglbarcode/libglbarcode-3.0-sections.txt | 46 +++++
docs/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 ++++++++++++++++++++
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 +-
18 files changed, 930 insertions(+), 39 deletions(-)
---
diff --git a/.gitignore b/.gitignore
index 84676e3..0753561 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 37b047d..973bcd7 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 0cb4945..a0be5c8 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 0000000..1bed761
--- /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 0000000..7d9724d
--- /dev/null
+++ b/docs/libglbarcode/intro.sgml
@@ -0,0 +1,161 @@
+<refentry id="libglbarcode-intro" revision="07 Nov 2010">
+<refmeta>
+<refentrytitle role="top_of_page" id="libglbarcode-intro.top_of_page">Introduction</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>
+ LIBGLBARCODE-3.0 Library
+</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Introduction</refname>
+<refpurpose>
+Introduction to libglbarcode library
+</refpurpose>
+</refnamediv>
+
+
+<refsect1>
+<title>Overview</title>
+
+<para>
+Libglbarcode provides the core barcode functionality for <application>glabels</application>. 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
+<application>glabels</application>.
+</para>
+
+</refsect1>
+
+
+<refsect1>
+<title>Basic Usage</title>
+
+<programlisting>
+
+#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);
+}
+
+</programlisting>
+
+
+</refsect1>
+
+
+<refsect1>
+<title>Writing Renderers</title>
+
+<para>
+The <link linkend="lglBarcode">lglBarcode</link> 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.
+</para>
+
+<programlisting>
+
+#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;
+
+ }
+
+ }
+
+}
+
+
+</programlisting>
+
+
+</refsect1>
+
+
+</refentry>
diff --git a/docs/libglbarcode/libglbarcode-3.0-docs.sgml b/docs/libglbarcode/libglbarcode-3.0-docs.sgml
new file mode 100644
index 0000000..d04ced2
--- /dev/null
+++ b/docs/libglbarcode/libglbarcode-3.0-docs.sgml
@@ -0,0 +1,31 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd";
+[
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+ <!ENTITY libglbarcode-intro SYSTEM "intro.sgml">
+]>
+<book id="index">
+
+ <bookinfo>
+ <title>LibGlbarcode 3.0 Reference Manual</title>
+ </bookinfo>
+
+ <chapter id="overview">
+ <title>LibGlbarcode Overview</title>
+
+ &libglbarcode-intro;
+
+ </chapter>
+
+ <chapter id="api">
+ <title>API Reference</title>
+
+ <xi:include href="xml/lgl-barcode.xml"/>
+ <xi:include href="xml/lgl-barcode-create.xml"/>
+ <xi:include href="xml/lgl-barcode-render-to-cairo.xml"/>
+ <xi:include href="xml/lgl-barcode-type.xml"/>
+
+ </chapter>
+
+</book>
diff --git a/docs/libglbarcode/libglbarcode-3.0-overrides.txt b/docs/libglbarcode/libglbarcode-3.0-overrides.txt
new file mode 100644
index 0000000..e69de29
diff --git a/docs/libglbarcode/libglbarcode-3.0-sections.txt b/docs/libglbarcode/libglbarcode-3.0-sections.txt
new file mode 100644
index 0000000..0eb153c
--- /dev/null
+++ b/docs/libglbarcode/libglbarcode-3.0-sections.txt
@@ -0,0 +1,46 @@
+<SECTION>
+<FILE>lgl-barcode</FILE>
+<INCLUDE>libglbarcode/lgl-barcode.h</INCLUDE>
+<SUBSECTION Barcode Structure>
+lglBarcode
+<SUBSECTION Barcode Structure Management>
+lgl_barcode_new
+lgl_barcode_free
+<SUBSECTION Barcode Drawing Primitives>
+lglBarcodeShapeType
+lglBarcodeShape
+lglBarcodeShapeAny
+lglBarcodeShapeLine
+lglBarcodeShapeBox
+lglBarcodeShapeChar
+lglBarcodeShapeString
+lglBarcodeShapeRing
+lglBarcodeShapeHexagon
+<SUBSECTION Barcode Construction>
+lgl_barcode_add_line
+lgl_barcode_add_box
+lgl_barcode_add_char
+lgl_barcode_add_string
+lgl_barcode_add_ring
+lgl_barcode_add_hexagon
+</SECTION>
+
+<SECTION>
+<FILE>lgl-barcode-create</FILE>
+<INCLUDE>libglbarcode/lgl-barcode-create.h</INCLUDE>
+lgl_barcode_create
+</SECTION>
+
+<SECTION>
+<FILE>lgl-barcode-render-to-cairo</FILE>
+<INCLUDE>libglbarcode/lgl-barcode-render-to-cairo.h</INCLUDE>
+lgl_barcode_render_to_cairo
+lgl_barcode_render_to_cairo_path
+</SECTION>
+
+<SECTION>
+<FILE>lgl-barcode-type</FILE>
+<INCLUDE>libglbarcode/lgl-barcode-type.h</INCLUDE>
+lglBarcodeType
+</SECTION>
+
diff --git a/docs/libglbarcode/libglbarcode-3.0.types b/docs/libglbarcode/libglbarcode-3.0.types
new file mode 100644
index 0000000..e69de29
diff --git a/docs/libglbarcode/tmpl/lgl-barcode-create.sgml b/docs/libglbarcode/tmpl/lgl-barcode-create.sgml
new file mode 100644
index 0000000..7d1e9e7
--- /dev/null
+++ b/docs/libglbarcode/tmpl/lgl-barcode-create.sgml
@@ -0,0 +1,37 @@
+<!-- ##### SECTION Title ##### -->
+Barcode Factory
+
+<!-- ##### SECTION Short_Description ##### -->
+Basic end-user barcode creation API
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+This section describes a simple API to select and create #glBarcode structures using a built-in
+barcode backend.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### SECTION Image ##### -->
+
+
+<!-- ##### FUNCTION lgl_barcode_create ##### -->
+<para>
+
+</para>
+
+ 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 0000000..4793828
--- /dev/null
+++ b/docs/libglbarcode/tmpl/lgl-barcode-render-to-cairo.sgml
@@ -0,0 +1,40 @@
+<!-- ##### SECTION Title ##### -->
+Cairo Renderer
+
+<!-- ##### SECTION Short_Description ##### -->
+Render barcode to cairo context
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+This section describes the cairo barcode renderer.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### SECTION Image ##### -->
+
+
+<!-- ##### FUNCTION lgl_barcode_render_to_cairo ##### -->
+<para>
+
+</para>
+
+ bc:
+ cr:
+
+
+<!-- ##### FUNCTION lgl_barcode_render_to_cairo_path ##### -->
+<para>
+
+</para>
+
+ 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 0000000..c7c1d6f
--- /dev/null
+++ b/docs/libglbarcode/tmpl/lgl-barcode-type.sgml
@@ -0,0 +1,36 @@
+<!-- ##### SECTION Title ##### -->
+Barcode Types
+
+<!-- ##### SECTION Short_Description ##### -->
+Enumeration of supported barcode types
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+This section describes an enumeration for selecting one of the barcode types supported by libglbarcode.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### SECTION Image ##### -->
+
+
+<!-- ##### ENUM lglBarcodeType ##### -->
+<para>
+This enumeration is used to select a built-in barcode type. The currently supported barcode types are
+</para>
+
+ 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 0000000..0d10991
--- /dev/null
+++ b/docs/libglbarcode/tmpl/lgl-barcode.sgml
@@ -0,0 +1,214 @@
+<!-- ##### SECTION Title ##### -->
+lglBarcode
+
+<!-- ##### SECTION Short_Description ##### -->
+Barcode structure
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+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.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### SECTION Image ##### -->
+
+
+<!-- ##### STRUCT lglBarcode ##### -->
+<para>
+
+</para>
+
+ width:
+ height:
+ shapes:
+
+<!-- ##### FUNCTION lgl_barcode_new ##### -->
+<para>
+
+</para>
+
+ void:
+ Returns:
+
+
+<!-- ##### FUNCTION lgl_barcode_free ##### -->
+<para>
+
+</para>
+
+ bc:
+
+
+<!-- ##### ENUM lglBarcodeShapeType ##### -->
+<para>
+
+</para>
+
+ LGL_BARCODE_SHAPE_LINE:
+ LGL_BARCODE_SHAPE_BOX:
+ LGL_BARCODE_SHAPE_CHAR:
+ LGL_BARCODE_SHAPE_STRING:
+ LGL_BARCODE_SHAPE_RING:
+ LGL_BARCODE_SHAPE_HEXAGON:
+
+<!-- ##### UNION lglBarcodeShape ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### STRUCT lglBarcodeShapeAny ##### -->
+<para>
+
+</para>
+
+ type:
+ x:
+ y:
+
+<!-- ##### STRUCT lglBarcodeShapeLine ##### -->
+<para>
+
+</para>
+
+ type:
+ x:
+ y:
+ length:
+ width:
+
+<!-- ##### STRUCT lglBarcodeShapeBox ##### -->
+<para>
+
+</para>
+
+ type:
+ x:
+ y:
+ width:
+ height:
+
+<!-- ##### STRUCT lglBarcodeShapeChar ##### -->
+<para>
+
+</para>
+
+ type:
+ x:
+ y:
+ fsize:
+ c:
+
+<!-- ##### STRUCT lglBarcodeShapeString ##### -->
+<para>
+
+</para>
+
+ type:
+ x:
+ y:
+ fsize:
+ string:
+
+<!-- ##### STRUCT lglBarcodeShapeRing ##### -->
+<para>
+
+</para>
+
+ type:
+ x:
+ y:
+ radius:
+ line_width:
+
+<!-- ##### STRUCT lglBarcodeShapeHexagon ##### -->
+<para>
+
+</para>
+
+ type:
+ x:
+ y:
+ height:
+
+<!-- ##### FUNCTION lgl_barcode_add_line ##### -->
+<para>
+
+</para>
+
+ bc:
+ x:
+ y:
+ length:
+ width:
+
+
+<!-- ##### FUNCTION lgl_barcode_add_box ##### -->
+<para>
+
+</para>
+
+ bc:
+ x:
+ y:
+ width:
+ height:
+
+
+<!-- ##### FUNCTION lgl_barcode_add_char ##### -->
+<para>
+
+</para>
+
+ bc:
+ x:
+ y:
+ fsize:
+ c:
+
+
+<!-- ##### FUNCTION lgl_barcode_add_string ##### -->
+<para>
+
+</para>
+
+ bc:
+ x:
+ y:
+ fsize:
+ string:
+ length:
+
+
+<!-- ##### FUNCTION lgl_barcode_add_ring ##### -->
+<para>
+
+</para>
+
+ bc:
+ x:
+ y:
+ radius:
+ line_width:
+
+
+<!-- ##### FUNCTION lgl_barcode_add_hexagon ##### -->
+<para>
+
+</para>
+
+ 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 0000000..e69de29
diff --git a/libglbarcode/lgl-barcode-create.c b/libglbarcode/lgl-barcode-create.c
index fe2dadc..f149c97 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 1dd1700..79a2222 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 43634d7..9fc0b9f 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 25409d8..ab2c636 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.
+ *
+ * <note><para>
+ * This function is intended to be used internally by barcode implementations.
+ * Typically an end-user would use lgl_barcode_create() instead.
+ * </para></note>
+ *
+ *
+ * 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 ).
+ *
+ * <note><para>
+ * This function is intended to be used internally by barcode implementations.
+ * </para></note>
+ *
+ */
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 ).
+ *
+ * <note><para>
+ * This function is intended to be used internally by barcode implementations.
+ * </para></note>
+ *
+ */
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 ).
+ *
+ * <note><para>
+ * This function is intended to be used internally by barcode implementations.
+ * </para></note>
+ *
+ */
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 ).
+ *
+ * <note><para>
+ * This function is intended to be used internally by barcode implementations.
+ * </para></note>
+ *
+ */
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 ).
+ *
+ * <note><para>
+ * This function is intended to be used internally by barcode implementations.
+ * </para></note>
+ *
+ */
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 ).
+ *
+ * <note><para>
+ * This function is intended to be used internally by barcode implementations.
+ * </para></note>
+ *
+ */
void
lgl_barcode_add_hexagon (lglBarcode *bc,
gdouble x,
diff --git a/libglbarcode/lgl-barcode.h b/libglbarcode/lgl-barcode.h
index f7f9a07..bcbfbfd 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.
+ *
+ *<programlisting>
*
* @ = origin (x,y) from top left corner of barcode
*
@@ -122,6 +146,10 @@ typedef struct {
* | |
* +-----+
* width
+ *
+ *</programlisting>
+ *
+ * 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.
+ *
+ *<programlisting>
*
* @ = origin (x,y) from top left corner of barcode
*
@@ -151,6 +189,10 @@ typedef struct {
* | |
* +---------+
* width
+ *
+ *</programlisting>
+ *
+ * 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.
+ *
+ *<programlisting>
*
* @ = origin (x,y) from top left corner of barcode
*
@@ -179,6 +231,10 @@ typedef struct {
* /__/ \__\ |
* v
* @ ----------------------
+ *
+ *</programlisting>
+ *
+ * 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.
+ *
+ *<programlisting>
*
* @ = origin (x,y) from top left corner of barcode
*
@@ -208,6 +275,10 @@ typedef struct {
* v
* @ ------------------
* x = horizontal center
+ *
+ *</programlisting>
+ *
+ * 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.
+ *
+ *<programlisting>
*
* @ = origin (x,y) is centre of circle
*
@@ -237,6 +318,10 @@ typedef struct {
* \ `.____.' / | radius
* `._ ...._.'.......|
* `-....-'
+ *
+ *</programlisting>
+ *
+ * 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.
+ *
+ *<programlisting>
*
* @ = origin (x,y) is top of hexagon
*
@@ -272,6 +366,9 @@ typedef struct {
* "-_ _-" v
* " ------------------
*
+ *</programlisting>
+ *
+ * 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 bdcbf6d..325eff2 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 bad41ee..e0ee61f 100644
--- a/libglbarcode/libglbarcode.h
+++ b/libglbarcode/libglbarcode.h
@@ -28,8 +28,9 @@
#include <libglbarcode/lgl-barcode-render-to-cairo.h>
-#include <libglbarcode/lgl-barcode-postnet.h>
+#include <libglbarcode/lgl-barcode-code39.h>
#include <libglbarcode/lgl-barcode-onecode.h>
+#include <libglbarcode/lgl-barcode-postnet.h>
#endif /* __LIBGLBARCODE_H__ */
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
