From: Jim Evins Date: Tue, 2 Oct 2007 03:05:06 +0000 (+0000) Subject: 2007-10-01 Jim Evins X-Git-Tag: glabels-2_3_0~323 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=52befabc0173ee7dcd6e4e662cc60e57c7240c98;p=glabels 2007-10-01 Jim Evins * docs/libglabels/libglabels-decl-list.txt: * docs/libglabels/libglabels-docs.sgml: * docs/libglabels/libglabels-sections.txt: * docs/libglabels/libglabels-undocumented.txt: * docs/libglabels/tmpl/category.sgml: * docs/libglabels/tmpl/enums.sgml: * docs/libglabels/tmpl/init.sgml: * docs/libglabels/tmpl/libglabels-unused.sgml: * docs/libglabels/tmpl/paper.sgml: * docs/libglabels/tmpl/template-construction.sgml: * docs/libglabels/tmpl/template-db.sgml: * docs/libglabels/tmpl/template-misc.sgml: * docs/libglabels/tmpl/template-struct.sgml: * docs/libglabels/tmpl/template.sgml: * docs/libglabels/tmpl/xml-category.sgml: * docs/libglabels/tmpl/xml-template.sgml: * libglabels/category.h: * libglabels/init.c: * libglabels/libglabels-private.h: * libglabels/paper.h: * libglabels/template.c: * libglabels/template.h: * libglabels/xml-template.h: Basic documentation framework for libglabels updated. This still needs some fleshing out. git-svn-id: https://glabels.svn.sourceforge.net/svnroot/glabels/trunk@675 f5e0f49d-192f-0410-a22d-a8d8700d0965 --- diff --git a/glabels2/ChangeLog b/glabels2/ChangeLog index b6381355..fc92273b 100644 --- a/glabels2/ChangeLog +++ b/glabels2/ChangeLog @@ -1,3 +1,31 @@ +2007-10-01 Jim Evins + + * docs/libglabels/libglabels-decl-list.txt: + * docs/libglabels/libglabels-docs.sgml: + * docs/libglabels/libglabels-sections.txt: + * docs/libglabels/libglabels-undocumented.txt: + * docs/libglabels/tmpl/category.sgml: + * docs/libglabels/tmpl/enums.sgml: + * docs/libglabels/tmpl/init.sgml: + * docs/libglabels/tmpl/libglabels-unused.sgml: + * docs/libglabels/tmpl/paper.sgml: + * docs/libglabels/tmpl/template-construction.sgml: + * docs/libglabels/tmpl/template-db.sgml: + * docs/libglabels/tmpl/template-misc.sgml: + * docs/libglabels/tmpl/template-struct.sgml: + * docs/libglabels/tmpl/template.sgml: + * docs/libglabels/tmpl/xml-category.sgml: + * docs/libglabels/tmpl/xml-template.sgml: + * libglabels/category.h: + * libglabels/init.c: + * libglabels/libglabels-private.h: + * libglabels/paper.h: + * libglabels/template.c: + * libglabels/template.h: + * libglabels/xml-template.h: + Basic documentation framework for libglabels updated. This still needs some + fleshing out. + 2007-09-27 Jim Evins * docs/libglabels/libglabels-decl-list.txt: diff --git a/glabels2/docs/libglabels/libglabels-decl-list.txt b/glabels2/docs/libglabels/libglabels-decl-list.txt index d6a29794..29a29582 100644 --- a/glabels2/docs/libglabels/libglabels-decl-list.txt +++ b/glabels2/docs/libglabels/libglabels-decl-list.txt @@ -26,7 +26,6 @@ lgl_xml_template_parse_templates_doc lgl_xml_template_parse_template_node lgl_xml_template_write_templates_to_file lgl_xml_template_write_template_to_file -lgl_xml_template_create_templates_doc lgl_xml_template_create_template_node @@ -56,7 +55,6 @@ lglTemplateFrameShape lglTemplateFrame lglTemplateMarkupType lglTemplateMarkup -lgl_template_init lgl_template_register lgl_template_get_name_list_unique lgl_template_get_name_list_all @@ -75,8 +73,8 @@ lgl_template_add_alias lgl_template_frame_rect_new lgl_template_frame_round_new lgl_template_frame_cd_new -lgl_template_add_layout -lgl_template_add_markup +lgl_template_frame_add_layout +lgl_template_frame_add_markup lgl_template_layout_new lgl_template_markup_margin_new lgl_template_markup_line_new @@ -116,7 +114,6 @@ lgl_init
category lglCategory -lgl_category_init lgl_category_new lgl_category_dup lgl_category_free @@ -131,7 +128,6 @@ lgl_category_lookup_name_from_id
paper lglPaper -lgl_paper_init lgl_paper_new lgl_paper_dup lgl_paper_free diff --git a/glabels2/docs/libglabels/libglabels-docs.sgml b/glabels2/docs/libglabels/libglabels-docs.sgml index 3d8059cb..b9b412c3 100644 --- a/glabels2/docs/libglabels/libglabels-docs.sgml +++ b/glabels2/docs/libglabels/libglabels-docs.sgml @@ -8,21 +8,27 @@ LibGlabels Reference Manual - + Basic LibGlabels Usage - + + Templates + + + + + - + - + Working Directly With LibGlabels XML - + diff --git a/glabels2/docs/libglabels/libglabels-sections.txt b/glabels2/docs/libglabels/libglabels-sections.txt index 38385777..c012a17f 100644 --- a/glabels2/docs/libglabels/libglabels-sections.txt +++ b/glabels2/docs/libglabels/libglabels-sections.txt @@ -14,7 +14,6 @@ lglUnitsType paper libglabels/paper.h lglPaper -lgl_paper_init lgl_paper_new lgl_paper_dup lgl_paper_free @@ -35,7 +34,6 @@ lgl_paper_print_known_papers category libglabels/category.h lglCategory -lgl_category_init lgl_category_new lgl_category_dup lgl_category_free @@ -48,57 +46,71 @@ lgl_category_lookup_name_from_id
-template +template-struct libglabels/template.h lglTemplate +lglTemplateFrameShape +lglTemplateFrame lglTemplateFrameAll lglTemplateFrameRect lglTemplateFrameRound lglTemplateFrameCD lglTemplateLayout +lglTemplateMarkupType +lglTemplateMarkup lglTemplateMarkupMargin lglTemplateMarkupLine lglTemplateMarkupCircle lglTemplateMarkupRect lglTemplateOrigin -lglTemplateFrameShape -lglTemplateFrame -lglTemplateMarkupType -lglTemplateMarkup -lgl_template_init -lgl_template_register -lgl_template_get_name_list_unique -lgl_template_get_name_list_all -lgl_template_free_name_list -lgl_template_from_name lgl_template_get_first_frame lgl_template_does_page_size_match lgl_template_does_category_match lgl_template_frame_get_size lgl_template_frame_get_n_labels lgl_template_frame_get_origins +
+ +
+template-db +libglabels/template.h +lgl_template_get_name_list_unique +lgl_template_get_name_list_all +lgl_template_free_name_list +lgl_template_from_name +lgl_template_register +
+ +
+template-construction +libglabels/template.h lgl_template_new +lgl_template_dup +lgl_template_free lgl_template_add_category lgl_template_add_frame lgl_template_add_alias lgl_template_frame_rect_new lgl_template_frame_round_new lgl_template_frame_cd_new -lgl_template_add_layout -lgl_template_add_markup +lgl_template_frame_dup +lgl_template_frame_free +lgl_template_frame_add_layout +lgl_template_frame_add_markup lgl_template_layout_new +lgl_template_layout_dup +lgl_template_layout_free lgl_template_markup_margin_new lgl_template_markup_line_new lgl_template_markup_circle_new lgl_template_markup_rect_new -lgl_template_dup -lgl_template_free -lgl_template_frame_dup -lgl_template_frame_free -lgl_template_layout_dup -lgl_template_layout_free lgl_template_markup_dup lgl_template_markup_free +
+ +
+template-misc +libglabels/template.h lgl_template_print_known_templates lgl_template_print_aliases
diff --git a/glabels2/docs/libglabels/libglabels-undocumented.txt b/glabels2/docs/libglabels/libglabels-undocumented.txt index 27c5f539..7bde80b2 100644 --- a/glabels2/docs/libglabels/libglabels-undocumented.txt +++ b/glabels2/docs/libglabels/libglabels-undocumented.txt @@ -1,7 +1,7 @@ -55% symbol docs coverage. -71 symbols documented. +85% symbol docs coverage. +111 symbols documented. 0 symbols incomplete. -57 not documented. +19 not documented. LGL_XML_NAME_SPACE @@ -23,43 +23,5 @@ lglTemplateMarkupRect lglTemplateMarkupType lglTemplateOrigin lglUnitsType -lgl_template_add_alias -lgl_template_add_category -lgl_template_add_frame -lgl_template_add_layout -lgl_template_add_markup -lgl_template_does_category_match -lgl_template_does_page_size_match -lgl_template_dup -lgl_template_frame_cd_new -lgl_template_frame_dup -lgl_template_frame_free -lgl_template_frame_get_n_labels -lgl_template_frame_get_origins -lgl_template_frame_get_size -lgl_template_frame_rect_new -lgl_template_frame_round_new -lgl_template_free -lgl_template_free_name_list -lgl_template_from_name -lgl_template_get_first_frame -lgl_template_get_name_list_all -lgl_template_get_name_list_unique -lgl_template_init -lgl_template_layout_dup -lgl_template_layout_free -lgl_template_layout_new -lgl_template_markup_circle_new -lgl_template_markup_dup -lgl_template_markup_free -lgl_template_markup_line_new -lgl_template_markup_margin_new -lgl_template_markup_rect_new -lgl_template_new -lgl_template_print_aliases -lgl_template_print_known_templates -lgl_template_register -lgl_xml_template_create_templates_doc -init:Long_Description diff --git a/glabels2/docs/libglabels/tmpl/category.sgml b/glabels2/docs/libglabels/tmpl/category.sgml new file mode 100644 index 00000000..2e880b2e --- /dev/null +++ b/glabels2/docs/libglabels/tmpl/category.sgml @@ -0,0 +1,107 @@ + +Categories + + +Template category definitions + + + +This section describes a structure for representing categories of stationary and related +functions. + + + + + + + + + + + + + + + +@id: +@name: + + + + + + +@id: +@name: +@Returns: + + + + + + + +@orig: +@Returns: + + + + + + + +@category: + + + + + + + +@Returns: + + + + + + + +@names: + + + + + + + +@name: +@Returns: + + + + + + + +@id: +@Returns: + + + + + + + +@name: +@Returns: + + + + + + + +@id: +@Returns: + + diff --git a/glabels2/docs/libglabels/tmpl/enums.sgml b/glabels2/docs/libglabels/tmpl/enums.sgml index 86ba624d..963555e8 100644 --- a/glabels2/docs/libglabels/tmpl/enums.sgml +++ b/glabels2/docs/libglabels/tmpl/enums.sgml @@ -1,5 +1,5 @@ -Basic Enumerations +Enumerations Common enumerations used by libglabels diff --git a/glabels2/docs/libglabels/tmpl/init.sgml b/glabels2/docs/libglabels/tmpl/init.sgml index e14a31aa..14024cbf 100644 --- a/glabels2/docs/libglabels/tmpl/init.sgml +++ b/glabels2/docs/libglabels/tmpl/init.sgml @@ -1,12 +1,12 @@ -Library Initialization +Initialization Initialization of the LibGlabels library. - +This section describes the LibGlabels initialization function. diff --git a/glabels2/docs/libglabels/tmpl/libglabels-unused.sgml b/glabels2/docs/libglabels/tmpl/libglabels-unused.sgml index f6e47fdd..6c3f01a2 100644 --- a/glabels2/docs/libglabels/tmpl/libglabels-unused.sgml +++ b/glabels2/docs/libglabels/tmpl/libglabels-unused.sgml @@ -22,6 +22,79 @@ libglabels + + +This section describes a set of structures representing stationary templates and related +functions. + + + + + + + + + + +Template definitions + + + + + + + +Templates + + + + + + + + + + + + + + + + + + + + + + + +template2 + + + + + + + + + + + + + + + + + + + + + + + +template3 + + @@ -1103,3 +1176,45 @@ the CSS2 Specification (Section 4.3.2). @templates: @utf8_filename: + + + + + + + + + + + + + + + + + +@frame: +@layout: + + + + + + +@frame: +@markup: + + + + + + + + + + + + +@templates: +@Returns: + diff --git a/glabels2/docs/libglabels/tmpl/paper.sgml b/glabels2/docs/libglabels/tmpl/paper.sgml index f783b05e..40850c0f 100644 --- a/glabels2/docs/libglabels/tmpl/paper.sgml +++ b/glabels2/docs/libglabels/tmpl/paper.sgml @@ -28,13 +28,6 @@ and related functions. @width: @height: - - - - - - - diff --git a/glabels2/docs/libglabels/tmpl/template-construction.sgml b/glabels2/docs/libglabels/tmpl/template-construction.sgml new file mode 100644 index 00000000..55da76bb --- /dev/null +++ b/glabels2/docs/libglabels/tmpl/template-construction.sgml @@ -0,0 +1,243 @@ + +Construction Functions + + +Functions to help create new templates + + + +This section describes a set of functions for constructing new template structures. + + + + + + + + + + + + + + + +@name: +@description: +@page_size: +@page_width: +@page_height: +@Returns: + + + + + + + +@orig_template: +@Returns: + + + + + + + +@template: + + + + + + + +@template: +@category: + + + + + + + +@template: +@frame: + + + + + + + +@template: +@alias: + + + + + + + +@id: +@w: +@h: +@r: +@x_waste: +@y_waste: +@Returns: + + + + + + + +@id: +@r: +@waste: +@Returns: + + + + + + + +@id: +@r1: +@r2: +@w: +@h: +@waste: +@Returns: + + + + + + + +@orig_frame: +@Returns: + + + + + + + +@frame: + + + + + + + +@frame: +@layout: + + + + + + + +@frame: +@markup: + + + + + + + +@nx: +@ny: +@x0: +@y0: +@dx: +@dy: +@Returns: + + + + + + + +@orig_layout: +@Returns: + + + + + + + +@layout: + + + + + + + +@size: +@Returns: + + + + + + + +@x1: +@y1: +@x2: +@y2: +@Returns: + + + + + + + +@x0: +@y0: +@r: +@Returns: + + + + + + + +@x1: +@y1: +@w: +@h: +@r: +@Returns: + + + + + + + +@orig_markup: +@Returns: + + + + + + + +@markup: + + diff --git a/glabels2/docs/libglabels/tmpl/template-db.sgml b/glabels2/docs/libglabels/tmpl/template-db.sgml new file mode 100644 index 00000000..3241c832 --- /dev/null +++ b/glabels2/docs/libglabels/tmpl/template-db.sgml @@ -0,0 +1,65 @@ + +Database + + +Database of pre-defined templates + + + +This section describes a set of functions to locate pre-defined templates and add templates +to the LibGlabels template database. + + + + + + + + + + + + + + + +@page_size: +@category: +@Returns: + + + + + + + +@page_size: +@category: +@Returns: + + + + + + + +@names: + + + + + + + +@name: +@Returns: + + + + + + + +@template: + + diff --git a/glabels2/docs/libglabels/tmpl/template-misc.sgml b/glabels2/docs/libglabels/tmpl/template-misc.sgml new file mode 100644 index 00000000..1b773d7c --- /dev/null +++ b/glabels2/docs/libglabels/tmpl/template-misc.sgml @@ -0,0 +1,34 @@ + +Miscellaneous Functions + + +Miscellaneous template functions + + + +This section describes miscellaneous template functions. + + + + + + + + + + + + + + + + + + + + + + +@template: + + diff --git a/glabels2/docs/libglabels/tmpl/template-struct.sgml b/glabels2/docs/libglabels/tmpl/template-struct.sgml new file mode 100644 index 00000000..aad3e0c6 --- /dev/null +++ b/glabels2/docs/libglabels/tmpl/template-struct.sgml @@ -0,0 +1,235 @@ + +The lglTemplate Structure + + +How templates are represented in memory + + + +This section describes a set of structures that represent a template in memory. It also +describes functions for querying such structures. + + + + + + + + + + + + + + + +@name: +@description: +@page_size: +@page_width: +@page_height: +@categories: +@frames: +@aliases: + + + + + + +@LGL_TEMPLATE_FRAME_SHAPE_RECT: +@LGL_TEMPLATE_FRAME_SHAPE_ROUND: +@LGL_TEMPLATE_FRAME_SHAPE_CD: + + + + + + + + + + + + +@shape: +@id: +@layouts: +@markups: + + + + + + +@shape: +@id: +@layouts: +@markups: +@w: +@h: +@r: +@x_waste: +@y_waste: + + + + + + +@shape: +@id: +@layouts: +@markups: +@r: +@waste: + + + + + + +@shape: +@id: +@layouts: +@markups: +@r1: +@r2: +@w: +@h: +@waste: + + + + + + +@nx: +@ny: +@x0: +@y0: +@dx: +@dy: + + + + + + +@LGL_TEMPLATE_MARKUP_MARGIN: +@LGL_TEMPLATE_MARKUP_LINE: +@LGL_TEMPLATE_MARKUP_CIRCLE: +@LGL_TEMPLATE_MARKUP_RECT: + + + + + + + + + + + + +@type: +@size: + + + + + + +@type: +@x1: +@y1: +@x2: +@y2: + + + + + + +@type: +@x0: +@y0: +@r: + + + + + + +@type: +@x1: +@y1: +@w: +@h: +@r: + + + + + + +@x: +@y: + + + + + + +@template: +@Returns: + + + + + + + +@template: +@page_size: +@Returns: + + + + + + + +@template: +@category: +@Returns: + + + + + + + +@frame: +@w: +@h: + + + + + + + +@frame: +@Returns: + + + + + + + +@frame: +@Returns: + + diff --git a/glabels2/docs/libglabels/tmpl/template.sgml b/glabels2/docs/libglabels/tmpl/template.sgml deleted file mode 100644 index 592e9bbd..00000000 --- a/glabels2/docs/libglabels/tmpl/template.sgml +++ /dev/null @@ -1,526 +0,0 @@ - -Templates - - -Template definitions - - - -This section describes a set of structures representing stationary templates and related -functions. - - - - - - - - - - - - - - - -@name: -@description: -@page_size: -@page_width: -@page_height: -@categories: -@frames: -@aliases: - - - - - - -@shape: -@id: -@layouts: -@markups: - - - - - - -@shape: -@id: -@layouts: -@markups: -@w: -@h: -@r: -@x_waste: -@y_waste: - - - - - - -@shape: -@id: -@layouts: -@markups: -@r: -@waste: - - - - - - -@shape: -@id: -@layouts: -@markups: -@r1: -@r2: -@w: -@h: -@waste: - - - - - - -@nx: -@ny: -@x0: -@y0: -@dx: -@dy: - - - - - - -@type: -@size: - - - - - - -@type: -@x1: -@y1: -@x2: -@y2: - - - - - - -@type: -@x0: -@y0: -@r: - - - - - - -@type: -@x1: -@y1: -@w: -@h: -@r: - - - - - - -@x: -@y: - - - - - - -@LGL_TEMPLATE_FRAME_SHAPE_RECT: -@LGL_TEMPLATE_FRAME_SHAPE_ROUND: -@LGL_TEMPLATE_FRAME_SHAPE_CD: - - - - - - - - - - - - -@LGL_TEMPLATE_MARKUP_MARGIN: -@LGL_TEMPLATE_MARKUP_LINE: -@LGL_TEMPLATE_MARKUP_CIRCLE: -@LGL_TEMPLATE_MARKUP_RECT: - - - - - - - - - - - - - - - - - - - -@template: - - - - - - - -@page_size: -@category: -@Returns: - - - - - - - -@page_size: -@category: -@Returns: - - - - - - - -@names: - - - - - - - -@name: -@Returns: - - - - - - - -@template: -@Returns: - - - - - - - -@template: -@page_size: -@Returns: - - - - - - - -@template: -@category: -@Returns: - - - - - - - -@frame: -@w: -@h: - - - - - - - -@frame: -@Returns: - - - - - - - -@frame: -@Returns: - - - - - - - -@name: -@description: -@page_size: -@page_width: -@page_height: -@Returns: - - - - - - - -@template: -@category: - - - - - - - -@template: -@frame: - - - - - - - -@template: -@alias: - - - - - - - -@id: -@w: -@h: -@r: -@x_waste: -@y_waste: -@Returns: - - - - - - - -@id: -@r: -@waste: -@Returns: - - - - - - - -@id: -@r1: -@r2: -@w: -@h: -@waste: -@Returns: - - - - - - - -@frame: -@layout: - - - - - - - -@frame: -@markup: - - - - - - - -@nx: -@ny: -@x0: -@y0: -@dx: -@dy: -@Returns: - - - - - - - -@size: -@Returns: - - - - - - - -@x1: -@y1: -@x2: -@y2: -@Returns: - - - - - - - -@x0: -@y0: -@r: -@Returns: - - - - - - - -@x1: -@y1: -@w: -@h: -@r: -@Returns: - - - - - - - -@orig: -@Returns: - - - - - - - -@template: - - - - - - - -@orig_frame: -@Returns: - - - - - - - -@frame: - - - - - - - -@orig_layout: -@Returns: - - - - - - - -@layout: - - - - - - - -@orig_markup: -@Returns: - - - - - - - -@markup: - - - - - - - - - - - - - - -@template: - - diff --git a/glabels2/docs/libglabels/tmpl/xml-category.sgml b/glabels2/docs/libglabels/tmpl/xml-category.sgml new file mode 100644 index 00000000..f22b59ed --- /dev/null +++ b/glabels2/docs/libglabels/tmpl/xml-category.sgml @@ -0,0 +1,47 @@ + +XML Category Functions + + +Functions to parse glabels XML category definition files + + + +This section describes a number of functions for parsing glabels +XML category definition files. + + + + + + + + + + + + + + + +@utf8_filename: +@Returns: + + + + + + + +@categories_doc: +@Returns: + + + + + + + +@category_node: +@Returns: + + diff --git a/glabels2/docs/libglabels/tmpl/xml-template.sgml b/glabels2/docs/libglabels/tmpl/xml-template.sgml index 40060a6d..5591b9d4 100644 --- a/glabels2/docs/libglabels/tmpl/xml-template.sgml +++ b/glabels2/docs/libglabels/tmpl/xml-template.sgml @@ -64,15 +64,6 @@ template files and document files. @utf8_filename: - - - - - -@templates: -@Returns: - - diff --git a/glabels2/libglabels/category.h b/glabels2/libglabels/category.h index 43c17c23..84817da0 100644 --- a/glabels2/libglabels/category.h +++ b/glabels2/libglabels/category.h @@ -44,12 +44,6 @@ struct _lglCategory { }; -/* - * Module initialization - */ -void lgl_category_init (void); - - /* * Category construction */ diff --git a/glabels2/libglabels/init.c b/glabels2/libglabels/init.c index 61ccbc1f..609c323c 100644 --- a/glabels2/libglabels/init.c +++ b/glabels2/libglabels/init.c @@ -47,10 +47,12 @@ /** * lgl_init: * - * Initialize all libglabels subsystems. This function reads in all files - * containing paper definitions, category definitions, and templates to build - * its template data base. This function will search both system and user template - * directories for these files. + * Initialize all libglabels subsystems. An application should call lgl_init() once + * before calling any other libglabels functions. + * + * This function reads in all files containing paper definitions, category definitions, + * and templates to build its template data base. This function will search both system + * and user template directories for these files. */ void lgl_init (void) diff --git a/glabels2/libglabels/libglabels-private.h b/glabels2/libglabels/libglabels-private.h index c6c8d289..af98b90f 100644 --- a/glabels2/libglabels/libglabels-private.h +++ b/glabels2/libglabels/libglabels-private.h @@ -36,4 +36,9 @@ #undef G_LOG_DOMAIN #define G_LOG_DOMAIN "LibGlabels" +void lgl_template_init (void); +void lgl_paper_init (void); +void lgl_category_init (void); + + #endif /* __LIBGLABELS_PRIVATE_H__ */ diff --git a/glabels2/libglabels/paper.h b/glabels2/libglabels/paper.h index 25a5cb82..70c7cc77 100644 --- a/glabels2/libglabels/paper.h +++ b/glabels2/libglabels/paper.h @@ -45,12 +45,6 @@ struct _lglPaper { }; -/* - * Module initialization - */ -void lgl_paper_init (void); - - /* * Paper construction */ diff --git a/glabels2/libglabels/template.c b/glabels2/libglabels/template.c index e13ddb25..16c972e5 100644 --- a/glabels2/libglabels/template.c +++ b/glabels2/libglabels/template.c @@ -68,9 +68,14 @@ static gint compare_origins (gconstpointer a, gconstpointer b, gpointer user_data); -/*****************************************************************************/ -/* Initialize module. */ -/*****************************************************************************/ +/** + * lgl_template_init: + * + * Initialize libglabels template module by reading all paper definition + * files located in system and user template directories. + * + * The end user would typically call lgl_init() instead. + */ void lgl_template_init (void) { @@ -92,9 +97,13 @@ lgl_template_init (void) lgl_paper_free_id_list (page_sizes); } -/*****************************************************************************/ -/* Register template: if not in current list, add it. */ -/*****************************************************************************/ +/** + * lgl_template_register: + * @template: Pointer to a template structure to add to database. + * + * Register a template. This function adds a template to the template database. + * The template will be stored in an individual XML file in the user template directory. + */ void lgl_template_register (const lglTemplate *template) { @@ -144,9 +153,21 @@ lgl_template_register (const lglTemplate *template) } -/*********************************************************************************/ -/* Get a list of valid names of unique templates for given page size */ -/*********************************************************************************/ +/** + * lgl_template_get_name_list_unique: + * @page_size: If non NULL, limit results to given page size. + * @category: If non NULL, limit results to given template category. + * + * Get a list of valid names of unique templates in the template database. Results + * can be filtered by page size and/or template category. A list of valid page sizes + * can be obtained using lgl_paper_get_id_list(). A list of valid template categories + * can be obtained using lgl_category_get_id_list(). + * + * This function differs from lgl_template_get_name_list_all(), because it does not + * return multiple names for the same template. + * + * Returns: a list of template names. + */ GList * lgl_template_get_name_list_unique (const gchar *page_size, const gchar *category) @@ -174,9 +195,21 @@ lgl_template_get_name_list_unique (const gchar *page_size, return names; } -/*********************************************************************************/ -/* Get a list of all valid template names for given page size (includes aliases) */ -/*********************************************************************************/ +/** + * lgl_template_get_name_list_all: + * @page_size: If non NULL, limit results to given page size. + * @category: If non NULL, limit results to given template category. + * + * Get a list of valid names and aliases of unique templates in the template database. + * Results can be filtered by page size and/or template category. A list of valid page + * sizes can be obtained using lgl_paper_get_id_list(). A list of valid template + * categories can be obtained using lgl_category_get_id_list(). + * + * This function differs from lgl_template_get_name_list_unique(), because it will + * return multiple names for the same template. + * + * Returns: a list of template names and aliases. + */ GList * lgl_template_get_name_list_all (const gchar *page_size, const gchar *category) @@ -210,9 +243,14 @@ lgl_template_get_name_list_all (const gchar *page_size, return names; } -/*****************************************************************************/ -/* Free a list of template names. */ -/*****************************************************************************/ +/** + * lgl_template_free_name_list: + * @names: List of template name strings to be freed. + * + * Free up all storage associated with a list of template names obtained with + * lgl_template_get_name_list_all() or lgl_template_get_name_list_unique(). + * + */ void lgl_template_free_name_list (GList *names) { @@ -226,9 +264,15 @@ lgl_template_free_name_list (GList *names) g_list_free (names); } -/*****************************************************************************/ -/* Return a template structure from a name. */ -/*****************************************************************************/ +/** + * lgl_template_from_name: + * @name: name string + * + * Lookup template in template database from name string. + * + * Returns: pointer to a newly allocated #lglTemplate structure. + * + */ lglTemplate * lgl_template_from_name (const gchar *name) { @@ -259,9 +303,19 @@ lgl_template_from_name (const gchar *name) return lgl_template_dup ((lglTemplate *) templates->data); } -/*****************************************************************************/ -/* Get first label type in template. */ -/*****************************************************************************/ +/** + * lgl_template_get_first_frame: + * @template: #lglTemplate structure to query + * + * Lookup first #lglTemplateFrame in the given #lglTemplate. The returned + * value is simply a pointer to the given frame within the template and should + * not be freed. + * + * Note: glabels currently only supports a single frame per template. + * + * Returns: pointer to #lglTemplateFrame structure. + * + */ const lglTemplateFrame * lgl_template_get_first_frame (const lglTemplate *template) { @@ -270,9 +324,15 @@ lgl_template_get_first_frame (const lglTemplate *template) return (lglTemplateFrame *)template->frames->data; } -/****************************************************************************/ -/* Get raw label size (width and height). */ -/****************************************************************************/ +/** + * lgl_template_frame_get_size: + * @frame: #lglTemplateFrame structure to query + * @w: pointer to location to receive width of frame + * @h: pointer to location to receive height of frame + * + * Get size (width and height) of given #lglTemplateFrame in points. + * + */ void lgl_template_frame_get_size (const lglTemplateFrame *frame, gdouble *w, @@ -308,9 +368,15 @@ lgl_template_frame_get_size (const lglTemplateFrame *frame, } } -/****************************************************************************/ -/* Get total number of labels per sheet of a label type. */ -/****************************************************************************/ +/** + * lgl_template_frame_get_n_labels: + * @frame: #lglTemplateFrame structure to query + * + * Get total number of labels per sheet corresponding to the given frame. + * + * Returns: number of labels per sheet. + * + */ gint lgl_template_frame_get_n_labels (const lglTemplateFrame *frame) { @@ -329,9 +395,17 @@ lgl_template_frame_get_n_labels (const lglTemplateFrame *frame) return n_labels; } -/****************************************************************************/ -/* Get array of origins of individual labels. */ -/****************************************************************************/ +/** + * lgl_template_frame_get_origins: + * @frame: #lglTemplateFrame structure to query + * + * Get an array of label origins for the given frame. These origins represent the + * upper left hand corner of each label on a page corresponding to the given frame. + * The array should be freed using g_free(). + * + * Returns: A newly allocated array of #lglTemplateOrigin structures. + * + */ lglTemplateOrigin * lgl_template_frame_get_origins (const lglTemplateFrame *frame) { @@ -363,9 +437,22 @@ lgl_template_frame_get_origins (const lglTemplateFrame *frame) return origins; } -/*****************************************************************************/ -/* Create a new template with given properties. */ -/*****************************************************************************/ +/** + * lgl_template_new: + * @name: Template name + * @description: Template descriptions + * @page_size: Page size id + * @page_width: Page width in points, set to zero unless page_size="Other" + * @page_height: Page height in points, set to zero unless page_size="Other" + * + * Create a new template structure, with the given top-level attributes. The + * created template will have no initial aliases, categories, or frames + * associated with it. See lgl_template_add_alias(), lgl_template_add_category(), + * and lgl_template_add_frame() to add these. + * + * Returns: pointer to a newly allocated #lglTemplate structure. + * + */ lglTemplate * lgl_template_new (const gchar *name, const gchar *description, @@ -390,9 +477,16 @@ lgl_template_new (const gchar *name, return template; } -/*****************************************************************************/ -/* Does page size match given id? */ -/*****************************************************************************/ +/** + * lgl_template_does_page_size_match: + * @template: Pointer to template structure to test + * @page_size: Page size ID string + * + * This function tests if the page size of the template matches the given ID. + * + * Returns: TRUE if the template matches the given page size ID. + * + */ gboolean lgl_template_does_page_size_match (const lglTemplate *template, const gchar *page_size) @@ -408,9 +502,16 @@ lgl_template_does_page_size_match (const lglTemplate *template, return g_strcasecmp(page_size, template->page_size) == 0; } -/*****************************************************************************/ -/* Does category match given id? */ -/*****************************************************************************/ +/** + * lgl_template_does_category_match: + * @template: Pointer to template structure to test + * @category: Category ID string + * + * This function tests if the given template belongs to the given category ID. + * + * Returns: TRUE if the template matches the given category ID. + * + */ gboolean lgl_template_does_category_match (const lglTemplate *template, const gchar *category) @@ -436,36 +537,55 @@ lgl_template_does_category_match (const lglTemplate *template, return FALSE; } -/*****************************************************************************/ -/* Add category to category list of template. */ -/*****************************************************************************/ +/** + * lgl_template_add_frame: + * @template: Pointer to template structure + * @frame: Pointer to frame structure + * + * This function adds the given frame structure to the template. Once added, + * the frame structure belongs to the given template; do not attempt to free + * it. + * + * Note: Currently glabels only supports a single frame per template. + * + */ void -lgl_template_add_category (lglTemplate *template, - const gchar *category) +lgl_template_add_frame (lglTemplate *template, + lglTemplateFrame *frame) { g_return_if_fail (template); - g_return_if_fail (category); + g_return_if_fail (frame); - template->categories = g_list_append (template->categories, - g_strdup (category)); + template->frames = g_list_append (template->frames, frame); } -/*****************************************************************************/ -/* Add label type structure to label type list of template. */ -/*****************************************************************************/ +/** + * lgl_template_add_category: + * @template: Pointer to template structure + * @category: Category ID string + * + * This function adds the given category ID to a templates category list. + * + */ void -lgl_template_add_frame (lglTemplate *template, - lglTemplateFrame *frame) +lgl_template_add_category (lglTemplate *template, + const gchar *category) { g_return_if_fail (template); - g_return_if_fail (frame); + g_return_if_fail (category); - template->frames = g_list_append (template->frames, frame); + template->categories = g_list_append (template->categories, + g_strdup (category)); } -/*****************************************************************************/ -/* Add alias to alias list of template. */ -/*****************************************************************************/ +/** + * lgl_template_add_alias: + * @template: Pointer to template structure + * @alias: Alias string + * + * This function adds the given alias to a templates list of aliases. + * + */ void lgl_template_add_alias (lglTemplate *template, const gchar *alias) @@ -477,9 +597,20 @@ lgl_template_add_alias (lglTemplate *template, g_strdup (alias)); } -/*****************************************************************************/ -/* Create a new label type structure for a rectangular label. */ -/*****************************************************************************/ +/** + * lgl_template_frame_rect_new: + * @id: ID of frame. (This should currently always be "0"). + * @w: width of frame in points. + * @h: height of frame in points. + * @r: radius of rounded corners in points. (Should be 0 for square corners.) + * @x_waste: Amount of overprint to allow in the horizontal direction. + * @y_waste: Amount of overprint to allow in the vertical direction. + * + * This function creates a new template frame for a rectangular label or card. + * + * Returns: Pointer to newly allocated #lglTemplateFrame structure. + * + */ lglTemplateFrame * lgl_template_frame_rect_new (const gchar *id, gdouble w, @@ -504,9 +635,17 @@ lgl_template_frame_rect_new (const gchar *id, return frame; } -/*****************************************************************************/ -/* Create a new label type structure for a round label. */ -/*****************************************************************************/ +/** + * lgl_template_frame_round_new: + * @id: ID of frame. (This should currently always be "0"). + * @r: radius of label in points. + * @waste: Amount of overprint to allow. + * + * This function creates a new template frame for a round label. + * + * Returns: Pointer to newly allocated #lglTemplateFrame structure. + * + */ lglTemplateFrame * lgl_template_frame_round_new (const gchar *id, gdouble r, @@ -525,9 +664,20 @@ lgl_template_frame_round_new (const gchar *id, return frame; } -/*****************************************************************************/ -/* Create a new label type structure for a CD/DVD label. */ -/*****************************************************************************/ +/** + * lgl_template_frame_cd_new: + * @id: ID of frame. (This should currently always be "0"). + * @r1: outer radius of label in points. + * @r2: radius of center hole in points. + * @w: clip width of frame in points for business card CDs. Should be 0 for no clipping. + * @h: clip height of frame in points for business card CDs. Should be 0 for no clipping. + * @waste: Amount of overprint to allow. + * + * This function creates a new template frame for a CD/DVD label. + * + * Returns: Pointer to newly allocated #lglTemplateFrame structure. + * + */ lglTemplateFrame * lgl_template_frame_cd_new (const gchar *id, gdouble r1, @@ -552,12 +702,17 @@ lgl_template_frame_cd_new (const gchar *id, return frame; } -/*****************************************************************************/ -/* Add a layout to a label type. */ -/*****************************************************************************/ +/** + * lgl_template_frame_add_layout: + * @frame: Pointer to template frame to add layout to. + * @layout: Pointer to layout structure to add to frame. + * + * This function adds a layout structure to the given template frame. + * + */ void -lgl_template_add_layout (lglTemplateFrame *frame, - lglTemplateLayout *layout) +lgl_template_frame_add_layout (lglTemplateFrame *frame, + lglTemplateLayout *layout) { g_return_if_fail (frame); g_return_if_fail (layout); @@ -565,12 +720,17 @@ lgl_template_add_layout (lglTemplateFrame *frame, frame->all.layouts = g_list_append (frame->all.layouts, layout); } -/*****************************************************************************/ -/* Add a markup item to a label type. */ -/*****************************************************************************/ +/** + * lgl_template_frame_add_markup: + * @frame: Pointer to template frame to add markup to. + * @markup: Pointer to markup structure to add to frame. + * + * This function adds a markup structure to the given template frame. + * + */ void -lgl_template_add_markup (lglTemplateFrame *frame, - lglTemplateMarkup *markup) +lgl_template_frame_add_markup (lglTemplateFrame *frame, + lglTemplateMarkup *markup) { g_return_if_fail (frame); g_return_if_fail (markup); @@ -578,9 +738,20 @@ lgl_template_add_markup (lglTemplateFrame *frame, frame->all.markups = g_list_append (frame->all.markups, markup); } -/*****************************************************************************/ -/* Create new layout structure. */ -/*****************************************************************************/ +/** + * lgl_template_layout_new: + * @nx: Number of labels across. + * @ny: Number of labels down. + * @x0: X coordinate of the top-left corner of the top-left label in the layout in points. + * @y0: Y coordinate of the top-left corner of the top-left label in the layout in points. + * @dx: Horizontal pitch in points. This is the distance from left-edge to left-edge. + * @dy: Vertical pitch in points. This is the distance from top-edge to top-edge. + * + * This function creates a new layout structure with the given parameters. + * + * Returns: a newly allocated #lglTemplateLayout structure. + * + */ lglTemplateLayout * lgl_template_layout_new (gint nx, gint ny, @@ -603,9 +774,15 @@ lgl_template_layout_new (gint nx, return layout; } -/*****************************************************************************/ -/* Create new margin markup structure. */ -/*****************************************************************************/ +/** + * lgl_template_markup_margin_new: + * @size: margin size in points. + * + * This function creates a new margin markup structure. + * + * Returns: a newly allocated #lglTemplateMarkup structure. + * + */ lglTemplateMarkup * lgl_template_markup_margin_new (gdouble size) { @@ -619,9 +796,18 @@ lgl_template_markup_margin_new (gdouble size) return markup; } -/*****************************************************************************/ -/* Create new markup line structure. */ -/*****************************************************************************/ +/** + * lgl_template_markup_line_new: + * @x1: x coordinate of first endpoint. + * @y1: y coordinate of first endpoint. + * @x2: x coordinate of second endpoint. + * @y2: y coordinate of second endpoint. + * + * This function creates a new line markup structure. + * + * Returns: a newly allocated #lglTemplateMarkup structure. + * + */ lglTemplateMarkup * lgl_template_markup_line_new (gdouble x1, gdouble y1, @@ -641,9 +827,17 @@ lgl_template_markup_line_new (gdouble x1, return markup; } -/*****************************************************************************/ -/* Create new markup circle structure. */ -/*****************************************************************************/ +/** + * lgl_template_markup_circle_new: + * @x0: x coordinate of center of circle. + * @y0: y coordinate of center of circle. + * @r: radius of circle. + * + * This function creates a new circle markup structure. + * + * Returns: a newly allocated #lglTemplateMarkup structure. + * + */ lglTemplateMarkup * lgl_template_markup_circle_new (gdouble x0, gdouble y0, @@ -661,9 +855,19 @@ lgl_template_markup_circle_new (gdouble x0, return markup; } -/*****************************************************************************/ -/* Create new markup rect structure. */ -/*****************************************************************************/ +/** + * lgl_template_markup_rect_new: + * @x1: x coordinate of top-left corner of rectangle. + * @y1: y coordinate of top-left corner of rectangle. + * @w: width of rectangle. + * @h: height of rectangle. + * @r: radius of rounded corner. + * + * This function creates a new rectangle markup structure. + * + * Returns: a newly allocated #lglTemplateMarkup structure. + * + */ lglTemplateMarkup * lgl_template_markup_rect_new (gdouble x1, gdouble y1, @@ -686,9 +890,15 @@ lgl_template_markup_rect_new (gdouble x1, } -/*****************************************************************************/ -/* Copy a template. */ -/*****************************************************************************/ +/** + * lgl_template_dup: + * @orig_template: Template to duplicate. + * + * This function duplicates a template structure. + * + * Returns: a newly allocated #lglTemplate structure. + * + */ lglTemplate * lgl_template_dup (const lglTemplate *orig_template) { @@ -728,9 +938,13 @@ lgl_template_dup (const lglTemplate *orig_template) return template; } -/*****************************************************************************/ -/* Free up a template. */ -/*****************************************************************************/ +/** + * lgl_template_free: + * @template: Template to free. + * + * This function frees all memory associated with given template structure. + * + */ void lgl_template_free (lglTemplate *template) { @@ -782,9 +996,15 @@ lgl_template_free (lglTemplate *template) } -/*****************************************************************************/ -/* Copy a template label type. */ -/*****************************************************************************/ +/** + * lgl_template_frame_dup: + * @orig_frame: Frame to duplicate. + * + * This function duplicates a template frame structure. + * + * Returns: a newly allocated #lglTemplateFrame structure. + * + */ lglTemplateFrame * lgl_template_frame_dup (const lglTemplateFrame *orig_frame) { @@ -846,9 +1066,13 @@ lgl_template_frame_dup (const lglTemplateFrame *orig_frame) return frame; } -/*****************************************************************************/ -/* Free up a template label type. */ -/*****************************************************************************/ +/** + * lgl_template_frame_free: + * @frame: Frame to free. + * + * This function frees all memory associated with given template frame structure. + * + */ void lgl_template_frame_free (lglTemplateFrame *frame) { @@ -887,9 +1111,15 @@ lgl_template_frame_free (lglTemplateFrame *frame) } -/*****************************************************************************/ -/* Duplicate layout structure. */ -/*****************************************************************************/ +/** + * lgl_template_layout_dup: + * @orig_layout: Layout to duplicate. + * + * This function duplicates a template layout structure. + * + * Returns: a newly allocated #lglTemplateLayout structure. + * + */ lglTemplateLayout * lgl_template_layout_dup (const lglTemplateLayout *orig_layout) { @@ -905,18 +1135,28 @@ lgl_template_layout_dup (const lglTemplateLayout *orig_layout) return layout; } -/*****************************************************************************/ -/* Free layout structure. */ -/*****************************************************************************/ +/** + * lgl_template_layout_free: + * @layout: Layout to free. + * + * This function frees all memory associated with given template layout structure. + * + */ void lgl_template_layout_free (lglTemplateLayout *layout) { g_free (layout); } -/*****************************************************************************/ -/* Duplicate markup structure. */ -/*****************************************************************************/ +/** + * lgl_template_markup_dup: + * @orig_markup: Markup to duplicate. + * + * This function duplicates a template markup structure. + * + * Returns: a newly allocated #lglTemplateMarkup structure. + * + */ lglTemplateMarkup * lgl_template_markup_dup (const lglTemplateMarkup *orig_markup) { @@ -931,9 +1171,13 @@ lgl_template_markup_dup (const lglTemplateMarkup *orig_markup) return markup; } -/*****************************************************************************/ -/* Free markup structure. */ -/*****************************************************************************/ +/** + * lgl_template_markup_free: + * @markup: Markup to free. + * + * This function frees all memory associated with given template markup structure. + * + */ void lgl_template_markup_free (lglTemplateMarkup *markup) { @@ -1086,9 +1330,12 @@ compare_origins (gconstpointer a, } } -/*****************************************************************************/ -/* Print all known templates (for debugging purposes). */ -/*****************************************************************************/ +/** + * lgl_template_print_known_templates: + * + * Print all known templates (for debugging purposes). + * + */ void lgl_template_print_known_templates (void) { @@ -1107,9 +1354,13 @@ lgl_template_print_known_templates (void) } -/*****************************************************************************/ -/* Print all aliases of a template (for debugging purposes). */ -/*****************************************************************************/ +/** + * lgl_template_print_aliases: + * @template: template + * + * Print all aliases of a template (for debugging purposes). + * + */ void lgl_template_print_aliases (const lglTemplate *template) { diff --git a/glabels2/libglabels/template.h b/glabels2/libglabels/template.h index 4bc91b03..83d04d3d 100644 --- a/glabels2/libglabels/template.h +++ b/glabels2/libglabels/template.h @@ -246,10 +246,8 @@ struct _lglTemplateOrigin { /* - * Module Initialization + * Template registration */ -void lgl_template_init (void); - void lgl_template_register (const lglTemplate *template); /* @@ -326,10 +324,10 @@ lglTemplateFrame *lgl_template_frame_cd_new (const gchar *id gdouble h, gdouble waste); -void lgl_template_add_layout (lglTemplateFrame *frame, +void lgl_template_frame_add_layout (lglTemplateFrame *frame, lglTemplateLayout *layout); -void lgl_template_add_markup (lglTemplateFrame *frame, +void lgl_template_frame_add_markup (lglTemplateFrame *frame, lglTemplateMarkup *markup); lglTemplateLayout *lgl_template_layout_new (gint nx, @@ -356,7 +354,7 @@ lglTemplateMarkup *lgl_template_markup_rect_new (gdouble x1 gdouble h, gdouble r); -lglTemplate *lgl_template_dup (const lglTemplate *orig); +lglTemplate *lgl_template_dup (const lglTemplate *orig_template); void lgl_template_free (lglTemplate *template); diff --git a/glabels2/libglabels/xml-template.h b/glabels2/libglabels/xml-template.h index ec704c2a..23377e6c 100644 --- a/glabels2/libglabels/xml-template.h +++ b/glabels2/libglabels/xml-template.h @@ -46,8 +46,6 @@ void lgl_xml_template_write_templates_to_file (GList *templ void lgl_xml_template_write_template_to_file (const lglTemplate *template, const gchar *utf8_filename); -xmlDocPtr lgl_xml_template_create_templates_doc (GList *templates); - void lgl_xml_template_create_template_node (const lglTemplate *template, xmlNodePtr root, const xmlNsPtr ns);