# 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.