/* Copyright (C) 2016-2020, Dirk Krause SPDX-License-Identifier: BSD-3-Clause */ /* WARNING: This file was generated by the dkct program (see http://dktools.sourceforge.net/ for details). Changes you make here will be lost if dkct is run again! You should modify the original source and run dkct on it. Original source: dk4paper.ctr */ #ifndef DK4PAPER_H_INCLUDED /** Avoid multiple inclusions. */ #define DK4PAPER_H_INCLUDED 1 #line 9 "dk4paper.ctr" /** @file dk4paper.h Read paper sizes. */ #ifndef DK4CONF_H_INCLUDED #if DK4_BUILDING_DKTOOLS4 #include "dk4conf.h" #else #include #endif #endif #ifndef DK4TYPES_H_INCLUDED #if DK4_BUILDING_DKTOOLS4 #include "dk4types.h" #else #include #endif #endif #if DK4_HAVE_MATH_H #ifndef MATH_H_INCLUDED #if DK4_ON_WINDOWS #ifndef _USE_MATH_DEFINES #define _USE_MATH_DEFINES 1 #endif #endif #include #define MATH_H_INCLUDED 1 #endif #endif #ifndef DK4ERROR_H_INCLUDED #if DK4_BUILDING_DKTOOLS4 #include "dk4error.h" #else #include #endif #endif #ifndef DK4STO_H_INCLUDED #if DK4_BUILDING_DKTOOLS4 #include "dk4sto.h" #else #include #endif #endif /** One paper size. */ typedef struct { dkChar *name; /**< Paper format name. */ double w; /**< Paper width in PS points. */ double h; /**< Paper height. */ double i; /**< Left or inner border. */ double o; /**< Right or outer border. */ double t; /**< Top border. */ double b; /**< Bottom border. */ } dk4_paper_size_t; /** Collection of paper sizes read from files. */ typedef struct { dk4_sto_t *s_ps; /**< Storage for paper sizes. */ dk4_sto_it_t *i_ps; /**< Iterator through storage. */ } dk4_paper_size_collection_t; #ifdef __cplusplus extern "C" { #endif /** Open a new paper size collection with minimum entries only. @param erp Error report, may be NULL. */ dk4_paper_size_collection_t * dk4papersize_coll_open(dk4_er_t *erp); /** Open a new paper size collection, search for configuration files and apply them. Note: Programs using the dk4_app_t type should use the dk4app_get_paper_sizes() from the dk4papea module instead. @param progname Program name. @param grpname Program group name. @param erp Error report, may be NULL. @return Valid pointer on success, NULL on error. */ dk4_paper_size_collection_t * dk4papersize_coll_for_application( const dkChar *progname, const dkChar *grpname, dk4_er_t *erp ); /** Close paper size collection, release memory. @param ptr Paper size collection to close. */ void dk4papersize_coll_close(dk4_paper_size_collection_t *ptr); /** Find a specific paper size in the collection. Note: Do not mix search and traversal mechanism, use exactly one method from the following three: - Find paper size entry by name using dk4papersize_coll_find(), - Get number of paper sizes using dk4papersize_coll_size() and use dk4papersize_coll_get() to get an entry for a given index, - Reset the collection using dk4papersize_coll_reset() and retrieve the next entry using dk4papersize_coll_next(), repeat dk4papersize_coll_next() until it returns NULL. All three methods use and modify the same internal container iterator, so mixing the methods is not a good idea. @param ptr Paper size collection to search for a paper size. @param name Name of paper size to find. @param erp Error report, may be NULL. @return Pointer to paper size on success, NULL on error or not found. */ const dk4_paper_size_t * dk4papersize_coll_find( dk4_paper_size_collection_t *ptr, const dkChar *name, dk4_er_t *erp ); /** Find a specific paper size in the collection, retrieve index in collection. Note: Do not mix search and traversal mechanism, use exactly one method from the following three: - Find paper size entry by name using dk4papersize_coll_find(), - Get number of paper sizes using dk4papersize_coll_size() and use dk4papersize_coll_get() to get an entry for a given index, - Reset the collection using dk4papersize_coll_reset() and retrieve the next entry using dk4papersize_coll_next(), repeat dk4papersize_coll_next() until it returns NULL. All three methods use and modify the same internal container iterator, so mixing the methods is not a good idea. @param ptr Paper size collection to search for a paper size. @param name Name of paper size to find. @param ppsi Address of variable to store the index of the named paper size within the collection, may be NULL. @param erp Error report, may be NULL. @return Pointer to paper size on success, NULL on error or not found. */ const dk4_paper_size_t * dk4papersize_coll_find_with_index( dk4_paper_size_collection_t *ptr, const dkChar *name, size_t *ppsi, dk4_er_t *erp ); /** Get number of paper sizes stored in the collection. Note: Do not mix search and traversal mechanism, use exactly one method from the following three: - Find paper size entry by name using dk4papersize_coll_find(), - Get number of paper sizes using dk4papersize_coll_size() and use dk4papersize_coll_get() to get an entry for a given index, - Reset the collection using dk4papersize_coll_reset() and retrieve the next entry using dk4papersize_coll_next(), repeat dk4papersize_coll_next() until it returns NULL. All three methods use and modify the same internal container iterator, so mixing the methods is not a good idea. @param ptr Paper size collection to query. @return Positive number of paper sizes on success, 0 on error. */ size_t dk4papersize_coll_size(dk4_paper_size_collection_t *ptr); /** Get paper size entry from collection by number. Note: Do not mix search and traversal mechanism, use exactly one method from the following three: - Find paper size entry by name using dk4papersize_coll_find(), - Get number of paper sizes using dk4papersize_coll_size() and use dk4papersize_coll_get() to get an entry for a given index, - Reset the collection using dk4papersize_coll_reset() and retrieve the next entry using dk4papersize_coll_next(), repeat dk4papersize_coll_next() until it returns NULL. All three methods use and modify the same internal container iterator, so mixing the methods is not a good idea. @param ptr Paper size collection to query. @param n Index of paper size entry, 0 for the first. @return Valid pointer on success, NULL on error. */ const dk4_paper_size_t * dk4papersize_coll_get(dk4_paper_size_collection_t *ptr, size_t n); /** Reset collection (start traversing at beginning). Note: Do not mix search and traversal mechanism, use exactly one method from the following three: - Find paper size entry by name using dk4papersize_coll_find(), - Get number of paper sizes using dk4papersize_coll_size() and use dk4papersize_coll_get() to get an entry for a given index, - Reset the collection using dk4papersize_coll_reset() and retrieve the next entry using dk4papersize_coll_next(), repeat dk4papersize_coll_next() until it returns NULL. All three methods use and modify the same internal container iterator, so mixing the methods is not a good idea. @param ptr Paper size collection to reset. */ void dk4papersize_coll_reset(dk4_paper_size_collection_t *ptr); /** Get next paper size from collection. Note: Do not mix search and traversal mechanism, use exactly one method from the following three: - Find paper size entry by name using dk4papersize_coll_find(), - Get number of paper sizes using dk4papersize_coll_size() and use dk4papersize_coll_get() to get an entry for a given index, - Reset the collection using dk4papersize_coll_reset() and retrieve the next entry using dk4papersize_coll_next(), repeat dk4papersize_coll_next() until it returns NULL. All three methods use and modify the same internal container iterator, so mixing the methods is not a good idea. @param ptr Paper size collection to query. @return Valid pointer on success, NULL on error or end of collection. */ const dk4_paper_size_t * dk4papersize_coll_next(dk4_paper_size_collection_t *ptr); /** Create a new paper size structure, allocate memory. @param name Name of paper size. @param erp Error report, may be NULL. @return Pointer to new paper size structure on success, NULL on error. */ dk4_paper_size_t * dk4papersize_new(const dkChar *name, dk4_er_t *erp); /** Destroy a paper size structure, release memory. @param pps Paper size structure to destroy. */ void dk4papersize_delete(dk4_paper_size_t *pps); /** Compare two paper sizes. @param l Left object pointer. @param r Right object or name pointer. @param cr Comparison criteria: 0=papersize/papersize, 1=papersize/name. @return Comparison result. */ int dk4papersize_cmp(const void *l, const void *r, int cr); /** Get paper width from paper size record. @param psptr Paper size record to query. @return Positive result on success, negative value on error. */ double dk4papersize_get_width(const dk4_paper_size_t *psptr); /** Get paper height from paper size record. @param psptr Paper size record to query. @return Positive result on success, negative value on error. */ double dk4papersize_get_height(const dk4_paper_size_t *psptr); /** Get left (inner) border from paper size record. @param psptr Paper size record to query. @return Non-negative result on success, negative value on error. */ double dk4papersize_get_left_border(const dk4_paper_size_t *psptr); /** Get right (outer) border from paper size record. @param psptr Paper size record to query. @return Non-negative result on success, negative value on error. */ double dk4papersize_get_right_border(const dk4_paper_size_t *psptr); /** Get top border from paper size record. @param psptr Paper size record to query. @return Non-negative result on success, negative value on error. */ double dk4papersize_get_top_border(const dk4_paper_size_t *psptr); /** Get bottom border from paper size record. @param psptr Paper size record to query. @return Non-negative result on success, negative value on error. */ double dk4papersize_get_bottom_border(const dk4_paper_size_t *psptr); /** Get name for paper size. @param psptr Paper size record to query. @return Valid pointer on success, NULL on error or empty name. */ const dkChar * dk4papersize_get_name(const dk4_paper_size_t *psptr); /** Find maximum difference between to paper sizes. @param l Left paper size. @param r Right paper size. @return Maximum difference of corresponding values. */ double dk4paper_difference(dk4_paper_size_t const *l, dk4_paper_size_t const *r); /** Find index of array element nearest to a given paper size. @param pres Address of result variable. @param a Array of paper sizes to test. @param sza Size of array a (number of elements). @param vptr Paper size to search for. @param erp Error report, may be NULL. @return 1 on success (pres variable was set), 0 on error. */ int dk4paper_find_nearest( size_t *pres, dk4_paper_size_t *a, size_t sza, dk4_paper_size_t *vptr, dk4_er_t *erp ); #ifdef __cplusplus } #endif /* vim: set ai sw=4 ts=4 : */ #endif