diff options
| -rw-r--r-- | README.md | 156 | ||||
| -rw-r--r-- | README.md.template | 5 | ||||
| -rw-r--r-- | def.go | 15 | ||||
| -rw-r--r-- | fpdf.go | 32 | ||||
| -rwxr-xr-x | mkdoc | 2 |
5 files changed, 207 insertions, 3 deletions
@@ -3,6 +3,160 @@ Package gofpdf implements a PDF document generator with high level support for text, drawing and images. -See the [documentation][1] for more details. +##Features +• Choice of measurement unit, page format and margins + +• Page header and footer management + +• Automatic page breaks, line breaks, and text justification + +• Inclusion of JPEG, PNG, GIF and basic path-only SVG images + +• Colors, gradients and alpha channel transparency + +• Outline bookmarks + +• Internal and external links + +• TrueType, Type1 and encoding support + +• Page compression + +• Lines, Bézier curves, arcs, and ellipses + +• Rotation, scaling, skewing, translation, and mirroring + +• Clipping + +• Document protection + +• Layers + +gofpdf has no dependencies other than the Go standard library. All tests pass +on Linux, Mac and Windows platforms. Like FPDF version 1.7, from which gofpdf +is derived, this package does not yet support UTF-8 fonts. However, support is +provided to translate UTF-8 runes to code page encodings. + +##Acknowledgments +This package's code and documentation are closely derived from the FPDF library +created by Olivier Plathey, and a number of font and image resources are copied +directly from it. Drawing support is adapted from the FPDF geometric figures +script by David Hernández Sanz. Transparency support is adapted from the FPDF +transparency script by Martin Hall-May. Support for gradients and clipping is +adapted from FPDF scripts by Andreas Würmser. Support for outline bookmarks is +adapted from Olivier Plathey by Manuel Cornes. Layer support is adapted from +Olivier Plathey. Support for transformations is adapted from the FPDF +transformation script by Moritz Wagner and Andreas Würmser. PDF protection is +adapted from the work of Klemen Vodopivec for the FPDF product. Lawrence +Kesteloot provided code to allow an image's extent to be determined prior to +placement. Support for vertical alignment within a cell was provided by Stefan +Schroeder. Ivan Daniluk generalized the font and image loading code to use the +Reader interface while maintaining backward compatibility. Anthony Starks +provided code for the Polygon function. Robert Lillack provided the Beziergon +function and corrected some naming issues with the internal curve function. +Claudio Felber provided implementations for dashed line drawing and generalized +font loading. Stani Michiels provided support for multi-segment path drawing +with smooth line joins, line join styles and enhanced fill modes. Bruno Michel +has provided valuable assistance with the code. + +The FPDF website is http://www.fpdf.org/. + +##License +gofpdf is released under the MIT License. It is copyrighted by Kurt Jung and +the contributors acknowledged above. + +##Installation +To install the package on your system, run + +``` +go get github.com/jung-kurt/gofpdf +``` + +Later, to receive updates, run + +``` +go get -u github.com/jung-kurt/gofpdf +``` + +##Quick Start +The following Go code generates a simple PDF and writes it to standard output. + +``` +pdf := gofpdf.New("P", "mm", "A4", "") +pdf.AddPage() +pdf.SetFont("Arial", "B", 16) +pdf.Cell(40, 10, "Hello, world") +pdf.Output(os.Stdout) +``` + +See the functions in the fpdf_test.go file (shown as examples in this +documentation) for more advanced PDF examples. + +##Errors +If an error occurs in an Fpdf method, an internal error field is set. After +this occurs, Fpdf method calls typically return without performing any +operations and the error state is retained. This error management scheme +facilitates PDF generation since individual method calls do not need to be +examined for failure; it is generally sufficient to wait until after Output() +is called. For the same reason, if an error occurs in the calling application +during PDF generation, it may be desirable for the application to transfer the +error to the Fpdf instance by calling the SetError() method or the SetErrorf() +method. At any time during the life cycle of the Fpdf instance, the error state +can be determined with a call to Ok() or Err(). The error itself can be +retrieved with a call to Error(). + +##Conversion Notes +This package is a relatively straightforward translation from the original FPDF +library written in PHP (despite the caveat in the introduction to Effective +Go). The API names have been retained even though the Go idiom would suggest +otherwise (for example, pdf.GetX() is used rather than simply pdf.X()). The +similarity of the two libraries makes the original FPDF website a good source +of information. It includes a forum and FAQ. + +However, some internal changes have been made. Page content is built up using +buffers (of type bytes.Buffer) rather than repeated string concatenation. +Errors are handled as explained above rather than panicking. Output is +generated through an interface of type io.Writer or io.WriteCloser. A number of +the original PHP methods behave differently based on the type of the arguments +that are passed to them; in these cases additional methods have been exported +to provide similar functionality. Font definition files are produced in JSON +rather than PHP. + +##Example PDFs +A side effect of running "go test" is the production of a number of example +PDFs. These can be found in the gofpdf/pdf directory after the tests complete. + +Please note that these examples run in the context of a test. In order run an +example as a standalone application, you'll need to examine fpdf_test.go for +some helper routines, for example exampleFilename and summary. + +##Nonstandard Fonts +Nothing special is required to use the standard PDF fonts (courier, helvetica, +times, zapfdingbats) in your documents other than calling SetFont(). + +In order to use a different TrueType or Type1 font, you will need to generate a +font definition file and, if the font will be embedded into PDFs, a compressed +version of the font file. This is done by calling the MakeFont function or +using the included makefont command line utility. To create the utility, cd +into the makefont subdirectory and run "go build". This will produce a +standalone executable named makefont. Select the appropriate encoding file from +the font subdirectory and run the command as in the following example. + +``` +./makefont --embed --enc=../font/cp1252.map --dst=../font ../font/calligra.ttf +``` + +In your PDF generation code, call AddFont() to load the font and, as with the +standard fonts, SetFont() to begin using it. Most examples, including the +package example, demonstrate this method. Good sources of free, open-source +fonts include http://www.google.com/fonts/ and http://dejavu-fonts.org/. + +##Roadmap +• Handle UTF-8 source text natively. Until then, automatic translation of +UTF-8 runes to code page bytes is provided. + +• Improve test coverage as reported by the coverage tool. + + [1]: http://godoc.org/github.com/jung-kurt/gofpdf diff --git a/README.md.template b/README.md.template new file mode 100644 index 0000000..c7b8987 --- /dev/null +++ b/README.md.template @@ -0,0 +1,5 @@ + + +{{.Doc}} + +[1]: http://godoc.org/github.com/jung-kurt/gofpdf @@ -76,10 +76,23 @@ type ImageInfoType struct { // value expressed in the unit of measure specified in New(). Since font // management in Fpdf uses points, this method can help with line height // calculations and other methods that require user units. -func (f *Fpdf) PointConvert(pt float64) float64 { +func (f *Fpdf) PointConvert(pt float64) (u float64) { return pt / f.k } +// PointToUnitConvert is an alias for PointConvert. +func (f *Fpdf) PointToUnitConvert(pt float64) (u float64) { + return pt / f.k +} + +// UnitToPointConvert returns the value of u, expressed in the unit of measure +// specified in New(), as a value expressed in points (1/72 inch). Since font +// management in Fpdf uses points, this method can help with setting font sizes +// based on the sizes of other non-font page elements. +func (f *Fpdf) UnitToPointConvert(u float64) (pt float64) { + return u * f.k +} + // Extent returns the width and height of the image in the units of the Fpdf // object. func (info *ImageInfoType) Extent() (wd, ht float64) { @@ -1528,7 +1528,8 @@ func (f *Fpdf) SetFont(familyStr, styleStr string, size float64) { return } -// SetFontSize defines the size of the current font in points. +// SetFontSize defines the size of the current font. Size is specified in +// points (1/ 72 inch). See also SetFontUnitSize(). func (f *Fpdf) SetFontSize(size float64) { if f.fontSizePt == size { return @@ -1540,6 +1541,19 @@ func (f *Fpdf) SetFontSize(size float64) { } } +// SetFontUnitSize defines the size of the current font. Size is specified in +// the unit of measure specified in New(). See also SetFontSize(). +func (f *Fpdf) SetFontUnitSize(size float64) { + if f.fontSize == size { + return + } + f.fontSizePt = size * f.k + f.fontSize = size + if f.page > 0 { + f.outf("BT /F%d %.2f Tf ET", f.currentFont.I, f.fontSizePt) + } +} + // GetFontSize returns the size of the current font in points followed by the // size in the unit of measure specified in New(). The second value can be used // as a line height value in drawing operations. @@ -2849,6 +2863,22 @@ func (f *Fpdf) outbuf(b *bytes.Buffer) { } } +// RawWriteStr writes a string directly to the PDF generation buffer. This is a +// low-level function that is not required for normal PDF construction. An +// understanding of the PDF specification is needed to use this method +// correctly. +func (f *Fpdf) RawWriteStr(str string) { + f.out(str) +} + +// RawWriteBuf writes the contents of the specified buffer directly to the PDF +// generation buffer. This is a low-level function that is not required for +// normal PDF construction. An understanding of the PDF specification is needed +// to use this method correctly. +func (f *Fpdf) RawWriteBuf(buf *bytes.Buffer) { + f.outbuf(buf) +} + // Add a formatted line to the document func (f *Fpdf) outf(fmtStr string, args ...interface{}) { f.out(sprintf(fmtStr, args...)) @@ -0,0 +1,2 @@ +# github.com/JImmyFrasche/autoreadme +autoreadme -f -template README.md.template |