pdf

Interface to create a PDF document.

File information

File	common/interface/pdf.h
Classes	IPdfProvider IPdf IPdfFont IPdfColor IPdfImage IPdfDocumentPosition IPdfPage IPdfImageStream IPdfTable UPdfTable IPdfTableHeader
class IPdfProvider members	CreatePdf
class IPdf members	SetInfo SetCompressionMode SetFont SetFontSize SetMargin AddFont FontWeight FontStyle AddColor AddPngImage AddPage Get
class IPdfDocumentPosition members	GetPage GetHorizontalPosition GetVerticalPosition Move MoveTo Clone
class IPdfPage members	GetPreviousPage GetNextPage GetSize GetDirection GetWidth GetHeight GetContentStart GetContentEnd SetSize SetDirection SetMargin AddText AddImage AddBackground AddHorizontalLine AddImageStream AddTable
class IPdfImageStream members	Write SetStreamWidth SetStreamHeight Draw
class IPdfTable members	SetFont SetContentMargin SetContentMargin SetHorizontalLine SetEvenRowBackground SetOddRowBackground AddHeader AddColumn AddRows GetEndPosition
class UPdfTable members	GetFieldContent GetHeaderContent
class IPdfTableHeader members	SetFont SetHorizontalLine

Classes

IPdfProvider

class IPdfProvider {
public:
    virtual ~IPdfProvider() { };
    virtual class IPdf * CreatePdf(class IInstanceLog * log = 0) = 0;
};

Public functions

CreatePdf

Creates an IPdf object. This object is to be deleted after use.

Parameters

class IInstanceLog log

If given and the app tracing is enabled, error messages are logged.

IPdf

class IPdf {
public:
    virtual ~IPdf() { };
    enum class InfoType {
        Author,
        Creator,
        Title,
        Subject,
        Keywords,
    };
    enum Compressions {
        CompressionNone     = 0x0,
        CompressionText     = 0x1,
        CompressionImage    = 0x2,
        CompressionMetaData = 0x4,
        CompressionAll      = 0xf,
    };
    enum Directions {
        DirectionPortrait,
        DirectionLandscape,
    };
    enum Sizes {
        SizeA4,
    };
    enum class DefaultFont {
        Courier,
        Helvetica,
        Times,
    };
    enum class FontWeight {
        Normal,
        Bold,
    };
    enum class FontStyle {
        Normal,
        Italic,
    };
    enum class TextHAlign {
        Left,
        Right,
        Center,
    };
    enum StreamTypes {
        StreamTypeCcittG31D,
    };
    virtual class IPdf &                    SetInfo(InfoType type, const char * info) = 0;
    virtual class IPdf &                    SetCompressionMode(unsigned compressionMode) = 0;
    virtual class IPdf &                    SetFont(const class IPdfFont * font) = 0;
    virtual class IPdf &                    SetFontSize(unsigned int fontSize) = 0;
    virtual class IPdf &                    SetMargin(float all) = 0;
    virtual class IPdf &                    SetMargin(float top, float right, float bottom, float left) = 0;
    virtual class IPdfFont *                AddFont(const char * fontFileName) = 0;
    virtual class IPdfFont *                AddFont(DefaultFont font = DefaultFont::Helvetica,
                                                    FontWeight weight = FontWeight::Normal,
                                                    FontStyle style = FontStyle::Normal) = 0;
    virtual const class IPdfColor *         AddColor(float gray) = 0;
    virtual class IPdfImage *               AddPngImage(const byte * data, unsigned int length) = 0;
    
    virtual class IPdfPage *                AddPage(enum IPdf::Sizes size = IPdf::SizeA4,
                                                    enum IPdf::Directions direction = IPdf::DirectionPortrait) = 0;
    virtual void                            Complete() = 0;         // Obsolete
    virtual void                            Get(const byte * & data, unsigned & length, bool * last = 0) = 0;
};

Public functions

SetInfo

With this function serveral information of the PDF file can be set. The types are: the author, the creator, the title, the subject or keywords.

Parameters

InfoType type	The type of the information which is set.
const char * info	The text in UTF-8 encoding.

Return value

Returns itself as reference.

SetCompressionMode

The function sets the compression mode of the PDF document.

Parameters

unsigned compressionMode

Bit mask which type of content should be compressed.

Return value

Returns itself as reference.

SetFont

Sets the current font to be used.

Parameters

const class IPdfFont * font

A font added to the document before.

Return value

Returns itself as reference.

SetFontSize

Sets the current font size to be used.

Parameters

unsigned int font-size

The font size.

Return value

Returns itself as reference.

SetMargin

Sets the margin of the document used for the first page. Further pages use the current margin of the last page.

Parameters

float all

Sets all four margins to this value.

SetMargin

Sets the margin of the document used for the first page. Further pages use the current margin of the last page.

Parameters

float top	The top margin value.
float right	The right margin value.
float bottom	The bottom margin value.
float left	The left margin value.

AddFont

Loads a true type font file exists in the local directory with the given file name for later usage. This font is embedded in the generated PDF file.

Parameters

const char * fontFileName

The file name of the font.

Return value

Returns the font handle if succeeds, otherwise zero.

AddFont

Adds a standard PDF font to the document which needn't to be embedded in the PDF file. The used encoding is LATIN-1. The expected UTF-8 text is transcribed into this encoding.

Parameters

DefaultFont font	(Default DefaultFont::Helvetica)The font.
FontWeight weight	(Default FontWeight::Normal)The font weight.
FontStyle style	(Default FontStyle::Normal)The font style.

Return value

Returns the font handle if succeeds, otherwise zero.

AddColor

Adds a gray value as color to the document for later usage.

Parameters

float gray

The gray value. Zero is black, one is white.

Return value

Returns the color handle.

AddPngImage

Loads a PNG image from memory which is embedded in the PDF file and can be shown at several document positions later.

Parameters

const byte * data	The PNG data.
unsigned int length	The PNG data length.

Return value

Returns the image handle if succeeds, otherwise zero.

AddPage

This function adds a new page to the document.

Parameters

enum IPdf::Sizes size	(Default IPdf::SizeA4) The size of the page.
enum IPdf::Directions direction	(Default IPdf::DirectionPortrait) The direction of the page.

Return value

Returns the new page.

Complete

The function is obsolete. Don't use it.

Get

Get the document data. The data pointer is set to a pointer allocated by IPdf. The end of the document is reached if length is zero or last is true.

Parameters

const byte * & data	Reference to the data pointer which is set by the function to the internal data.
unsigned & length	Reference to a unsigned variable which is set by the function to the data length.
bool * last	(Default 0) Reference to a bool variable, whose value is set by the function. The value is set to true if the end of the data is reached. This parameter can also be a null pointer, in which case it is not used.

IPdfFont

Overview

A font object handled by the PDF document.

IPdfColor

Overview

A color object handled by the PDF document.

IPdfImage

Overview

A image object handled by the PDF document.

IPdfPage

class IPdfPage {
public:
    virtual class IPdfPage *                    GetPreviousPage() = 0;
    virtual const class IPdfPage *              GetPreviousPage() const = 0;
    virtual class IPdfPage *                    GetNextPage() = 0;
    virtual const class IPdfPage *              GetNextPage() const = 0;
    virtual enum IPdf::Sizes                    GetSize() const = 0;
    virtual enum IPdf::Directions               GetDirection() const = 0;
    virtual float                               GetWidth() const = 0;
    virtual float                               GetHeight() const = 0;
    virtual const class IPdfDocumentPosition &  GetContentStart() const = 0;
    virtual const class IPdfDocumentPosition &  GetContentEnd() const = 0;
    virtual void                                SetSize(enum IPdf::Sizes size) = 0;
    virtual void                                SetDirection(enum IPdf::Directions direction) = 0;
    virtual void                                SetMargin(float all) = 0;
    virtual void                                SetMargin(float top, float right, float bottom, float left) = 0;
    
    virtual unsigned int                        AddText(const char *                        text,
                                                        const class IPdfDocumentPosition &  position,
                                                        IPdf::TextHAlign                    align = IPdf::TextHAlign::Left,
                                                        float                               maxWidth = 0,
                                                        float                               maxHeight = 0,
                                                        float *                             height = 0) = 0;
    virtual void                                AddImage(const class IPdfImage *    image,
                                                         float                      positionX,
                                                         float                      positionY,
                                                         float                      width,
                                                         float                      height) = 0;
    virtual void                                AddBackground(const class IPdfColor *               color,
                                                              const class IPdfDocumentPosition &    startPosition,
                                                              const class IPdfDocumentPosition &    endPosition) = 0;
    virtual void                                AddHorizontalLine(const class IPdfDocumentPosition &    startPosition,
                                                                  float                                 length,
                                                                  float                                 lineWidth,
                                                                  const class IPdfColor *               color) = 0;
    virtual class IPdfImageStream *             AddImageStream(enum IPdf::StreamTypes type) = 0;
    virtual class IPdfTable *                   AddTable(const class IPdfDocumentPosition * startPosition = 0) = 0;
    virtual void                                Complete() = 0;     // Obsolete
protected:
    virtual ~IPdfPage() { };
};

Public functions

GetPreviousPage

Gets the previous page of this page.

Return value

Returns a handle of a page, if a previous page exists, otherwise zero.

GetNextPage

Gets the next page of this page.

Return value

Returns a handle of a page, if a next page exists, otherwise zero.

GetSize

Gets the size format of this this page.

Return value

Returns the format type.

GetDirection

Gets the direction of this this page.

Return value

Returns the direction type: portrait or landscape.

GetWidth

Gets the page width.

Return value

Returns the width of the page.

GetHeight

Gets the page height.

Return value

Returns the height of the page.

GetContentStart

Gets the left upper position of this page which considers the page margin.

Return value

Returns a constant document position.

GetContentEnd

Gets the right lower position of this page which considers the page margin.

Return value

Returns a constant document position.

SetSize

Set the page size.

Parameters

enum IPdf::Sizes size

The supported size is A4.

SetDirection

Set the page direction.

Parameters

enum IPdf::Directions direction

Portrait or landscape.

SetMargin

Sets a new margin of the this page.

Parameters

float all

Sets all four margins to this value.

SetMargin

Sets a new margin of the this page.

Parameters

float top	The top margin value.
float right	The right margin value.
float bottom	The bottom margin value.
float left	The left margin value.

AddText

Adds UTF-8 encoded text within a given space to this page beginning at the given start position. The page of the document position is ignored, this page is used. No page break is done.

Parameters

const char * text	The text to be added.
const class IPdfDocumentPosition & position	The start position of the text.
IPdf::TextHAlign align	(Default IPdf::TextHAlign::Left) The horizontal alignment of the text.
float maxWidth	(Default 0) The available width for the text. If it is set, the page's right content margin is ignored, otherwise the width from the horizontal start position to the right content margin is used.
float maxHeight	(Default 0) The available height for the text. If it isn't set, the height from the vertical start position to the bottom margin is used. The configured page bottom margin isn't considered.
float * height	(Default 0) If the pointer is set, the used height is written.

Return value

Returns the number of the bytes which could be added on this page within the available space.

AddImage

Adds an image of the document to this page at the given position.

Parameters

const class IPdfImage * image	The image handle.
float positionX	The horizonal left position for the image in pixel.
float positionY	The vertical bottom position for the image in pixel.
float width	The width for the image in pixel.
float height	The height for the image in pixel.

AddBackground

Adds a background in the defined color within two corners.

Parameters

const class IPdfColor * color	A color handle.
const class IPdfDocumentPosition & startPosition	The left upper corner.
const class IPdfDocumentPosition & endPosition	The right lower corner.

AddHorizontalLine

Adds a horizontal line with a defined length, width and color on this page.

Parameters

const class IPdfDocumentPosition & startPosition	The start position for the line.
float length	The length of the line in pixel.
float lineWidth	The width of the line in pixel.
const class IPdfColor * color	The color of the line.

AddImageStream

Adds an image stream to the page.

Parameters

enum IPdf::StreamTypes type

The supported type is one-dimentional G3 data.

Return value

Returns a handle to the image stream.

AddTable

Adds a new table to this page.

Parameters

const class IPdfDocumentPosition * startPosition

(Default 0) If set, the table starts at this position within this page. Otherweise the content start position of this page is used.

Return value

Returns the handle of the new table.

Complete

This function is obsolete.

IPdfDocumentPosition

class IPdfDocumentPosition {
public:
    virtual class IPdfPage *                GetPage() const = 0;
    virtual float                           GetHorizontalPosition() const = 0;
    virtual float                           GetVerticalPosition() const = 0;
    virtual class IPdfDocumentPosition &    Move(float horizontalRight, float verticalDown) = 0;
    virtual class IPdfDocumentPosition &    MoveTo(const class IPdfDocumentPosition & position) = 0;
    virtual class IPdfDocumentPosition *    Clone() const = 0;
protected:
    IPdfDocumentPosition& operator=(const IPdfDocumentPosition&) = default;
    ~IPdfDocumentPosition() = default;
};

Overview

The IPdfDocumentPosition object handles a valid position within a PDF document.

Public functions

GetPage

Returns the page of this document position.

GetHorizontalPosition

Returns the horizontal position in pixel.

GetVerticalPosition

Returns the vertical position in pixel.

Move

Moves the current position within the current page for the given values in pixel in direction right and down.

Parameters

float horizontalRight	The value in pixel for the horizontal direction. A negative value moves left.
float verticalDown	The value in pixel for the vertical direction. A negative value moves upwards.

MoveTo

Moves to another given document position.

Parameters

const class IPdfDocumentPosition & position

The new position.

Clone

Returns a created document position with the current position. The object is handled by the PDF document, can be used, but not be deleted and is valid till the PDF document is deleted.

IPdfImageStream

class IPdfImageStream {
public:
    virtual ~IPdfImageStream() { };
    virtual void Write(const byte * data, unsigned length) = 0;
    virtual void SetStreamWidth(unsigned int width) = 0;
    virtual void SetStreamHeight(unsigned int height) = 0;
    virtual void Draw(float x, float y, float width, float height) = 0;
};

Public functions

Write

The function is to be called to write data into the image stream.

Parameters

const byte * data	Pointer to the data block to write.
unsigned length	Length of the data block to write.

SetStreamWidth

This function must be called to set the internal width parameter to the width of the written image.

Parameters

unsigned int width

The width in pixel.

SetStreamHeight

This function must be called to set the internal height parameter to the height of the written image.

Parameters

unsigned int height

The height in pixel.

Draw

The function is to be called if the stream is complete. After this, IPdfImageStream is invalid.

Parameters

float x	Horizontal start position of the image in the page.
float y	Vertical start position of the image in the page.
float width	Width of the image in the page.
float height	Height of the image in the page.

IPdfTable

class IPdfTable {
public:
    virtual ~IPdfTable() = default;
    virtual const class IPdfDocumentPosition &  GetEndPosition() const = 0;
    virtual class IPdfTable &                   SetFont(const class IPdfFont * font) = 0;
    virtual class IPdfTable &                   SetContentMargin(float all) = 0;
    virtual class IPdfTable &                   SetContentMargin(float top, float right, float bottom, float left) = 0;
    virtual class IPdfTable &                   SetHorizontalLine(float width, const class IPdfColor * color) = 0;
    virtual class IPdfTable &                   SetEvenRowBackground(const class IPdfColor * color) = 0;
    virtual class IPdfTable &                   SetOddRowBackground(const class IPdfColor * color) = 0;
    virtual class IPdfTableHeader *             AddHeader() = 0;
    virtual class IPdfTableColumn *             AddColumn(float             width,
                                                          IPdf::TextHAlign  align = IPdf::TextHAlign::Left) = 0;
    virtual void                                AddRows(class UPdfTable *   user,
                                                        unsigned int        count = 1) = 0;
};

Public functions

SetFont

Sets the font of the table content.

Parameters

const class IPdfFont * font

A font added to the document before.

SetContentMargin

Sets the margin width for the table content fields.

Parameters

float all

Sets all four margins to this value.

SetContentMargin

Sets the margin width for the table content fields.

Parameters

float top	The top margin value.
float right	The right margin value.
float bottom	The bottom margin value.
float left	The left margin value.

SetHorizontalLine

Configures a horizontal line between rows.

Parameters

float width	The line width in pixel.
const class IPdfColor * color	A color added to the document before.

SetEvenRowBackground

Sets the background color of the even rows.

Parameters

const class IPdfColor * color

A color added to the document before.

SetOddRowBackground

Sets the background color of the odd rows.

Parameters

const class IPdfColor * color

A color added to the document before.

AddHeader

Adds a table header to this table which can be configured. The header is added to the page with the first row added to the table.The UPdfTable object is used to get the table header content.

AddColumn

Defines a column added to the table. Must be called before rows are added.

Parameters

float width	The column width in pixel.
IPdf::TextHAlign align	The horizontal text alignment of this column.

AddRows

Adds a number of rows to this table. The UPdfTable object is used to get the field contents.

Parameters

class UPdfTable * user	A UPdfTable object for the call-back functions.
unsigned int count	The number of the rows to be addes to this table.

GetEndPosition

Gets the current end position of the table in the document.

UPdfTable

class UPdfTable {
public:
    virtual const char *    GetFieldContent(class IPdfTable *                   table,
                                            unsigned int                        row,
                                            unsigned int                        column,
                                            const class IPdfDocumentPosition &  startPosition,
                                            class IPdfDocumentPosition &        endPosition) = 0;
    virtual const char *    GetHeaderContent(class IPdfTable *                   table,
                                             unsigned int                        column,
                                             const class IPdfDocumentPosition &  startPosition,
                                             class IPdfDocumentPosition &        endPosition) { return 0; };
};

This class defines the call-back functions needed to use the IPdfTable.

Public functions

GetFieldContent

This function is called for every row is to be added to the table and for every column of the row. It gets the field content in the return value reference. This return value must be valid till the next function call or the AddRows function returns.

Parameters

class IPdfTable * table	It is set to the table which is called the AddRows function.
unsigned int row	It is set to the current row number beginning from zero.
unsigned int column	It is set to the current column number beginning from zero.
const class IPdfDocumentPosition & startPosition	It is set to the content field start position considered the left margin.
class IPdfDocumentPosition & endPosition	It is a given reference to the content field end position which can be changed to a lower vertical position to enhance the row height.

GetHeaderContent

This function is called for every column of the table header to get the field content in the return value reference. This return value must be valid till the next function call or the GetFieldContent function call.

Parameters

class IPdfTable * table	It is set to the table which is called the AddRows function.
unsigned int column	It is set to the current column number beginning from zero.
const class IPdfDocumentPosition & startPosition	It is set to the column start position considered the left margin.
class IPdfDocumentPosition & endPosition	It is a given reference to the content field end position which can be changed to a lower vertical position to enhance the header line height.

IPdfTableHeader

class IPdfTableHeader {
public:
    virtual class IPdfTableHeader &             SetFont(const class IPdfFont * font) = 0;
    virtual class IPdfTableHeader &             SetHorizontalLine(float width, const class IPdfColor * color) = 0;
protected:
    ~IPdfTableHeader() = default;
};

Public functions

SetFont

Sets the font of the table header text.

Parameters

const class IPdfFont * font

A font added to the document before.

SetHorizontalLine

Defines a horizontal line after the table header.

Parameters

float width	The line width in pixel.
const class IPdfColor * color	A color added to the document before.