Skip to content
Newer
Older
100644 405 lines (360 sloc) 17.2 KB
297ae85 initial commit
Chris authored
1 // -----------------------------------------------------------------------------------
2 // NKDBarcode.h
3 // -----------------------------------------------------------------------------------
4 // Created by Jeff LaMarche on Wed May 01 2002.
5 // Copyright (c) 2002 Naked Software. All rights reserved.
6 // -----------------------------------------------------------------------------------
7 // THIS SOURCE CODE IS PROVIDED AS-IS WITH NO WARRANTY OF ANY KIND
8 // -----------------------------------------------------------------------------------
9 // You may use and redistribute this source code without limitation
10 // -----------------------------------------------------------------------------------
11 /*!
12 @header NKDBarcode.h
13 NKDBarcode is a quasi-abstract class that contains state and actions common to generating many
14 different types of barcodes. It encapsulates much of the common behavior of the concrete subclasses that
15 implement varoius one dimensional (linear) barcodes. Subclasses will respond to a barcode message by
16 returning an NSString of 1s and 0s, assuming that a value of '1' represents a bar of the narrowest size needed
17 by this encoding scheme, and that '0' represents a gap of the same size.
18
19 If a subclass modifies this behavior, it should be well documented, and NKDBarcodeOffscreenView will possibly
20 have to be modified to accommodate the change.
21
22 Although most barcode specifications allow narrow bar widths as small as 7.5 mils, I am using a default
23 size of 13 mils for all barcodes that don't have strict bar-width requirements in their specification (e.g. PostNet)
24 because this is an acceptable bar width for most barcodes and many inkjet and laser printers have insufficient resolution
25 to produce a readable code on plain paper at bar widths smaller than this size.
26
27 The framework currently contains subclasses for Code 3 of 9, Extended Code 3 of 9, Interleaved Code
28 2 of 5, Modified Plessey and Modified Plessey Hex (not compliant with specs, untested), PostNet,
29 UPC-A, Code 128, Industrial 2 of 5, and EAN-13, Codabar, EAN-8 and UPC-E. In some cases, I do not have the complete
30 or official specifications. I also, unfortunately, do not have equipment to test some types of barcode, so I welcome
31 any help debugging, testing, and validating the encoding schemes of the provided subclasses. No guarantee is made concerning
32 the creation of readable code for any given hardware - I've done the best job that I could armed only with my PowerBook,
33 a Cue Cat and the specifications I could find.
34
35 If you have complete specifications or information about any dimensional linear barcodes or (for that matter) and other feedback,
36 please send it to me at <code>jeff_lamarche&#064;mac.com</code> and I will try to respond. Support for 2-dimensional (matrix)
37 barcodes is not currently planned as part of this framework, but if there's an interest, I'll consider adding it.
38 */
39 #import <Foundation/Foundation.h>
40
41 /*!
42 @defined kScreenResolution
43 @discussion This value is used to determine the drawing location of various bars. Though many
44 devices have different resolution, drawing in Cocoa seems to based on 72 pixels per inch
45 */
4ca08f7 increase dpi to reflect iphone
Chris authored
46 #define kScreenResolution 163.00
297ae85 initial commit
Chris authored
47
48 /*!
49 @class NKDBarcode
50 @abstract Superclass of concrete barcode classes.
51 @discussion The Naked Barcode Framework is designed to allow rapid creation and easy maintenance of
52 a set of classes for generating resolution independent one-dimensional linear barcodes. NKDBarcode is the root class
53 of the NKDBarcode framework.
54 */
55 @interface NKDBarcode : NSObject <NSCopying, NSCoding>
56 {
57 NSString *content;
58 float height;
59 float width;
60 char checkDigit;
61 float barWidth; // bar width in mils (thousands of an inch)
62 BOOL printsCaption;
63 float fontSize;
64 float captionHeight;
65 }
66
67 /*!
68 @method initWithContent:
69 @abstract Initializes new barcode object to encode provided data.
70 @param inContent A string containing the data to be encoded; should use only <B>ASCII-8</B> characters
71 (those that can be encoded using a single char in UTF-8)
72 @result Returns initialized NKDBarcode class
73 */
74 -(id)initWithContent: (NSString *)inContent;
75
76 /*!
77 @method initWithContent:printsCaption
78 @abstract Initializes new barcode object with provided data and specifies whether a caption should be printed
79 below the barcode.
80 @param inContent A string containing the data to be encoded; should use only <B>ASCII-8</B> characters
81 (those that can be encoded using a single char in UTF-8)
82 @param inPrints YES if caption should print.
83 @result Returns initialized NKDBarcode class
84 */
85 -(id)initWithContent: (NSString *)inContent
86 printsCaption: (BOOL)inPrints;
87
88 /*!
89 @method initWithContent:printsCaption:andBarWidth:andHeight:andFontSize:andCheckDigit:
90 @abstract Designated initializer for abstract barcode object.
91 @param inContent A string containing the data to be encoded; should use only <B>ASCII-8</B> characters
92 (those that can be encoded using a single char in UTF-8)
93 @param inPrints YES if caption should print.
94 @param inBarWidth Width of the smallest bar or gap to be used, in base units (points)
95 @param inHeight Height of the bar (excluding caption) in base units
96 @param inFontSize Size of the font to use for the caption
97 @param inDigit Check Digit either provided or calculated, -1 if not used or not yet calculated
98 @result Returns initialized NKDBarcode class
99 */
100 -(id)initWithContent: (NSString *)inContent
101 printsCaption: (BOOL)inPrints
102 andBarWidth: (float)inBarWidth
103 andHeight: (float)inHeight
104 andFontSize: (float)inFontSize
105 andCheckDigit: (char)inDigit;
106
107 /*!
108 @method setContent:
109 @abstract Sets the content to provided NSString.
110 @param inContent A string containing the data to be encoded; should use only <B>ASCII-8</B> characters
111 (those that can be encoded using a single char in UTF-8)
112 */
113 -(void)setContent:(NSString *)inContent;
114
115 /*!
116 @method setHeight:
117 @abstract Sets the barcode height to the provided value.
118 @param inHeight Value to set the height to.
119 */
120 -(void)setHeight:(float)inHeight;
121
122 /*!
123 @method setWidth:
124 @abstract Sets the barcode width to the provided value.
125 @param inWidth Value to set the width to.
126 */
127 -(void)setWidth:(float)inWidth;
128
129 /*!
130 @method setFontSize:
131 @abstract Sets the size of the font to use
132 @param inSize The size (as a float) of the font to use
133 */
134 -(void)setFontSize:(float)inSize;
135
136 /*!
137 @method setCaptionHeight:
138 @abstract: Set amount of space to leave under barcode for the caption
139 @param inHeight: Floating point amount of space to set (in inches)
140 */
141 -(void)setCaptionHeight:(float)inHeight;
142
143 /*!
144 @method captionHeight
145 @abstract Returns the amount of space to leave under the barcode for the caption
146 @result Floating point value representing the amount of space to leave (in inches)
147 */
148 -(float)captionHeight;
149
150 /*!
151 @method calculateWidth
152 @abstract Calculates the correct width for the barcode based on the encoding scheme and the specified bar width.
153 */
154 -(void)calculateWidth;
155
156 /*!
157 @method setCheckDigit:
158 @abstract Sets the check digit to the provided character.
159 @param inCheckDigit Character (char, not unichar) to set the check digit to.
160 */
161 -(void)setCheckDigit:(char)inCheckDigit;
162
163 /*!
164 @method setPrintsCaption:
165 @abstract Sets whether this barcode should print the content below the code.
166 @param inPrints Boolean value to specify whether the caption should print.
167 */
168 -(void)setPrintsCaption:(BOOL)inPrints;
169
170 /*!
171 @method setBarWidth:
172 @abstract Sets the width of a single bar (represented by a single 1 in the barcode string).
173 @param inBarWidth The value to use for the width of a single bar.
174 */
175 -(void)setBarWidth:(float)inBarWidth;
176
177 /*!
178 @method content
179 @abstract Accessor method for the data being encoded by this barcode.
180 @result Pointer to the NSString that stores the barcode's data.
181 */
182 -(NSString *)content;
183
184 /*!
185 @method height
186 @abstract Accessor method for the height of this barcode.
187 @result The current height of the barcode in inches.
188 */
189 -(float)height;
190
191 /*!
192 @method width
193 @abstract Accessor method for the width of this barcode.
194 @result The current width of this barcode in inches.
195 */
196 -(float)width;
197
198 /*!
199 @method checkDigit
200 @abstract Accessor method for the checkDigit for this barcode.
201 @discussion Many barcodes offer and some require a check digit that is calculated based on the rest of the content. This
202 value shouldn't print as part of the caption and will need to be recalculated if the content changes, so
203 it makes sense to store it separately
204 @result The check digit character (ASCII-8 char, not unichar)
205 */
206 -(char)checkDigit;
207
208 /*!
209 @method printsCaption
210 @abstract Accessor method for printsCaption.
211 @result YES if the content should be printed below the barcode.
212 */
213 -(BOOL)printsCaption;
214
215 /*!
216 @method barWidth
217 @abstract Accessor method for the current width of a single bar in inches
218 @result The current width in inches of a single bar or gap.
219 */
220 -(float)barWidth;
221
222 /*!
223 @method fontSize
224 @abstract returns the size of the font to use for the caption
225 @result Floating point value representing the size of the font (in points) to use for the caption
226 */
227 -(float) fontSize;
228
229 /*!
230 @method isSizeValid
231 @abstract (Deprecated) Returns true if the supplied image size provides sufficient
232 space to create a valid (open) barcode using this encoding scheme.
233 @discussion The first version of this barcode framework allowed the user to specify
234 the size of the barcode when it was instantiated. This method was
235 implemented as a check to make sure that the barcode that was created
236 didn't result in a barWidth less than the barcode's specification allowed
237 (usually 7.5 mils)
238 @result YES if the bar width at these settings is okay according to the specifications.
239 */
240 -(BOOL)isSizeValid;
241
242 /*!
243 @method generateChecksum
244 @abstract Generates the check digit or checksum for this barcode encoding scheme.
245 @discussion This can be overridden by objects implementing encoding schemes that
246 have a checksum algorithm. You can either require the entire, correct
247 number be passed in the constructor including the check digit (parsing
248 it out as appropriate, or you can accept the number without the checksum
249 and modify the content accordingly here.
250 */
251 -(void)generateChecksum;
252
253 /*!
254 @method isContentValid
255 @abstract Validates that this barcode supports the data it is encoding.
256 @discussion This method checks the actual content string to make sure that this encoding
257 scheme can encode the data it contains. For example, numeric-only schemes
258 should return false if a string with one or more letters is passed. If there
259 is a checksum used for the content. that can also be checked here. Don't
260 override if validation isn't desired or required.
261 */
262 -(BOOL) isContentValid;
263
264 /*!
265 @method initiator
266 @abstract Returns the encoded initiator or alignment bar(s)
267 @discussion Returns encoded string representing the left most character. While some barcodes
268 do not use this, many do have a required character of sequence of bars or gaps
269 that are used for calibration. Sublasses only need to override if such a character
270 is needed.
271 @result String of 0s and 1s representing the first (non-content) character or alignment bar(s).
272 */
273 -(NSString *)initiator;
274
275 /*!
276 @method terminator
277 @abstract Returns the encoded terminator or alignment bar(s)
278 @discussion Returns encoded string representing the right-most characte. While some barcodes
279 do not use this, many do have a required character of sequence of bars or gaps
280 that are used for calibration. Sublasses only need to override if such a character
281 is needed.
282 @result String of 0s and 1s representing the last (non-content) character or alignment bar(s).
283 */
284 -(NSString *)terminator;
285
286 /*!
287 @method _encodeChar
288 @abstract Private method to turn a single character into a string of 1s and 0s.
289 @discussion This routine returns an NSString representing a single character. This private method
290 is used by the default getBarcode function, which is responsible for ordering the
291 characters (if necessary and returning the entire encoded string, excluding the
292 terminator and initiator.
293 @result String of 0s and 1s representing inChar encoded for this barcode.
294 */
295 -(NSString *)_encodeChar:(char)inChar;
296
297 /*!
298 @method barcode:
299 @abstract Returns string of 0s and 1s representing the content for this type of barcode.
300 @discussion This method returns a string representing the entire barcode, excluding the initiator
301 and terminator.
302 @result String of 0s and 1s representing the content.
303 */
304 -(NSString *)barcode;
305
306 /*!
307 @method completeBarcode
308 @abstract Method to get the entire barcode as a string of 0s and 1s
309 @discussion Returns a string representing the entire barcode, including terminator and initiator.
310 @result String of 0s and 1s representing the entire barcode
311 */
312 -(NSString *)completeBarcode;
313
314 /*!
315 @method digitsToLeft
316 @abstract Returns number of digits to print to the left of the first bar.
317 @discussion For encoders with intruding captions such as UPC and EAN barcodes, this method
318 tells how many of the digits of the content should be printed to the left of the barcode,
319 rather than intruding on the barcode or printing below the barcode. This only needs to be
320 overridden if you need a value other than 0
321 @result The number of characters to print to the left.
322 */
323 -(int)digitsToLeft;
324
325 /*!
326 @method digitsToRight
327 @abstract Returns number of digits to print to the right of the last bar.
328 @discussion For encoders with intruding captions such as UPC and EAN barcodes, this method
329 tells how many of the digits of the content should be printed to the right of the barcode,
330 rather than intruding on the barcode or printing below the barcode. This only needs to be
331 overridden if you need a value other than 0
332 @result The number of characters to print to the right.
333 */
334 -(int)digitsToRight;
335
336 /*!
337 @method leftCaption
338 @abstract Returns string representing the characters to print to the left of the first bar
339 @discussion Returns string representing the portion of the caption that goes to the left of the barcode.
340 @result A string with the data to print to the left.
341 */
342 -(NSString *)leftCaption;
343
344 /*!
345 @method rightCaption
346 @abstract Returns string representing the characters to print to the right of the last bar
347 @discussion Returns string representing the portion of the caption that goes to the right of the barcode.
348 @result A string with the data to print to the right.
349 */
350 -(NSString *)rightCaption;
351
352 /*!
353 @method caption
354 @abstract Returns content to print below the barcode.
355 @result String representing the portion of the caption that goes under (or intrudes upon) the barcode.
356 */
357 -(NSString *)caption;
358
359 /*!
360 @method barBottom:
361 @abstract Designates the bottom of the bar within the barcode for the bar at a given index.
362 @discussion Given an index which corresponds to the bar / gap number (counting from left), where should
363 the bottom of the bar be. For most barcodes this value will always be the bottom of the barcode
364 excluding the caption, but some, like UPC and EAN have different bar bottoms for some bars.
365 Assumes that origin (0,0) is in lower left.
366 @param index The bar (from the left, 0-indexed) to specify the bottom position for.
367 @result The bottom of the bar in inches from the bottom of the barcode.
368 */
369 -(float)barBottom:(int)index;
370
371 /*!
372 @method barTop:
373 @abstract Designates the top of the bar within the barcode for the bar at a given index.
374 @discussion Given an index which corresponds to the bar/gap number (counting from left, 0-indexed),
375 this method will tell where the top of the bar should be. For most barcodes this value will
376 always be the top of the barcode excluding the caption, since most barcodes have a uniform top, but
377 some, like PostNet use different bar tops as part of the encoding scheme.
378 @param index The bar (from the left, 0 indexed) to specify the top position for.
379 @result The top of the bar in inches from the bottom of the barcode.
380 */
381 -(float)barTop:(int)index;
382
383 /*!
384 @method firstBar
385 @abstract Returns the position, from the left, specified in inches where the first bar prints
386 @discussion Returns the the horizontal position of the left edge of the first bar or gap. Typically, this is 0,
387 but some code, like EAN/UPC require some digits to print to the left and/or right of the code, meaning
388 that we need allocate some white space by skipping some pixels before drawing the first bar
389 @result The x-position in inches where the first bar prints
390 */
391 -(float)firstBar;
392
393 /*!
394 @method lastBar
395 @abstract Returns the position, from the left, specified in inches where the last bar ends
396 @discussion Returns the the horizontal position of the right edge of the last bar or gap. Typically, this is the
397 same as [barcode width] but some codes, like EAN/UPC require some digits to print to the left and/or
398 right of the code, meaning that we need allocate some white space by ending the codes before the end
399 of the barcode. This is generally the right edge of the last barcode less one barwidth
400 @result The x-position in inches where the last bar ends
401 */
402 -(float)lastBar;
403
404 @end
Something went wrong with that request. Please try again.