1/*
2 * "$Id: paper.h,v 1.4 2008/07/12 15:05:54 rlk Exp $"
3 *
4 *   libgimpprint paper functions.
5 *
6 *   Copyright 1997-2000 Michael Sweet (mike@easysw.com) and
7 *	Robert Krawitz (rlk@alum.mit.edu)
8 *
9 *   This program is free software; you can redistribute it and/or modify it
10 *   under the terms of the GNU General Public License as published by the Free
11 *   Software Foundation; either version 2 of the License, or (at your option)
12 *   any later version.
13 *
14 *   This program is distributed in the hope that it will be useful, but
15 *   WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
16 *   or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
17 *   for more details.
18 *
19 *   You should have received a copy of the GNU General Public License
20 *   along with this program; if not, write to the Free Software
21 *   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
22 */
23
24/**
25 * @file gutenprint/paper.h
26 * @brief Paper size functions.
27 */
28
29#ifndef GUTENPRINT_PAPER_H
30#define GUTENPRINT_PAPER_H
31
32#ifdef __cplusplus
33extern "C" {
34#endif
35
36#include <gutenprint/vars.h>
37
38/**
39 * The papersize describes the dimensions of a paper.
40 *
41 * @defgroup papersize papersize
42 * @{
43 */
44
45
46
47/**
48 * Units of measurement.
49 */
50typedef enum
51{
52  /** English/Imperial units. */
53  PAPERSIZE_ENGLISH_STANDARD,
54  /** Metric units. */
55  PAPERSIZE_METRIC_STANDARD,
56  /** English/Imperial units (optional paper, not displayed by default). */
57  PAPERSIZE_ENGLISH_EXTENDED,
58  /** Metric units (optional paper, not displayed by default). */
59  PAPERSIZE_METRIC_EXTENDED
60} stp_papersize_unit_t;
61
62typedef enum
63{
64  /** Standard paper size */
65  PAPERSIZE_TYPE_STANDARD = 0,
66  /** Envelope */
67  PAPERSIZE_TYPE_ENVELOPE
68} stp_papersize_type_t;
69
70/** The papersize data type. */
71typedef struct
72{
73  /** Short unique name (not translated). */
74  char *name;
75  /** Long descriptive name (translated). */
76  char *text;
77  /** Comment. */
78  char *comment;
79  /** Paper width. */
80  unsigned width;
81  /** Paper height. */
82  unsigned height;
83  /** Top margin. */
84  unsigned top;
85  /** Left margin. */
86  unsigned left;
87  /** Bottom margin. */
88  unsigned bottom;
89  /** Right margin. */
90  unsigned right;
91  /** Units of measurement. */
92  stp_papersize_unit_t paper_unit;
93  /** Paper size type. */
94  stp_papersize_type_t paper_size_type;
95} stp_papersize_t;
96
97/**
98 * Get the number of available papersizes.
99 * @returns the number of papersizes.
100 */
101extern int stp_known_papersizes(void);
102
103/**
104 * Get a papersize by name.
105 * @param name the short unique name of the paper.
106 * @returns a static pointer to the papersize, or NULL on failure.
107 */
108extern const stp_papersize_t *stp_get_papersize_by_name(const char *name);
109
110/**
111 * Get a papersize by size.
112 * The nearest available size to the size requested will be found.
113 * Only paper sizes within 5 points of width and height will be considered.
114 * @param length the length of the paper.
115 * @param width the width of the paper
116 * @returns a static pointer to the papersize, or NULL on failure.
117 */
118extern const stp_papersize_t *stp_get_papersize_by_size(int length,
119							int width);
120
121/**
122 * Get a papersize by size if an exact match is found.
123 * @param length the length of the paper.
124 * @param width the width of the paper
125 * @returns a static pointer to the papersize, or NULL on failure.
126 */
127extern const stp_papersize_t *stp_get_papersize_by_size_exact(int length,
128							      int width);
129
130/**
131 * Get a papersize by its index number.
132 * @param idx the index number.  This must not be greater than (total
133 * number of papers - 1).
134 * @returns a static pointer to the papersize, or NULL on failure.
135 */
136extern const stp_papersize_t *stp_get_papersize_by_index(int idx);
137
138/**
139 * Get the default paper dimensions for the current configuration.
140 * The default is derived from the PageSize parameter if set, otherwise
141 * the default page size for the printer is used.  If no value can be
142 * determined, 1x1 will be returned.
143 * @param v the Gutenprint vars object
144 * @param width pointer to storage that the width will be returned in.
145 * @param height pointer to storage that the height will be returned in.
146 */
147extern void stp_default_media_size(const stp_vars_t *v,
148				   int *width, int *height);
149
150/** @} */
151
152#ifdef __cplusplus
153  }
154#endif
155
156#endif /* GUTENPRINT_PAPER_H */
157/*
158 * End of "$Id: paper.h,v 1.4 2008/07/12 15:05:54 rlk Exp $".
159 */
160