pdftron::PDF::ElementWriter Class Reference

ElementWriter can be used to assemble and write new content to a page, Form XObject, Type3 Glyph stream, pattern stream, or any other content stream. More...

#include <ElementWriter.h>

List of all members.

Public Types

enum  WriteMode { e_underlay, e_overlay, e_replacement }
 Enumeration describing the placement of the element written to a page. More...

Public Member Functions

 ElementWriter ()
 ~ElementWriter ()
void Begin (Page &page, WriteMode placement=e_overlay, bool compress=true)
 Begin writing to the given page.
void Begin (const Page &page, bool background, bool compress=true)
 Begin writing to the given page.
void Begin (SDF::SDFDoc &doc, bool compress=true)
 Begin writing an Element sequence to a new stream.
void Begin (SDF::Obj stream_obj_to_update, bool compress=true)
 Begin writing an Element sequence to a stream.
SDF::Obj End ()
 Finish writing to a page.
void WriteElement (Element element)
 Writes the Element to the content stream.
void WritePlacedElement (Element element)
 A utility function that surrounds the given Element with a graphics state Save/Restore Element (i.e.
void Flush ()
 The Flush method flushes all pending Element writing operations.
void WriteBuffer (const char *data, int data_sz)
 Writes an arbitrary buffer to the content stream.
void WriteString (const char *str)
 Writes an arbitrary string to the content stream.


Detailed Description

ElementWriter can be used to assemble and write new content to a page, Form XObject, Type3 Glyph stream, pattern stream, or any other content stream.

Member Enumeration Documentation

Enumeration describing the placement of the element written to a page.

Enumerator:
e_underlay 
e_overlay  > element is put in the background layer of the page
e_replacement  > element appears on top of the existing graphics

> element will replace current page contents


Constructor & Destructor Documentation

pdftron::PDF::ElementWriter::ElementWriter (  ) 

pdftron::PDF::ElementWriter::~ElementWriter (  ) 


Member Function Documentation

void pdftron::PDF::ElementWriter::Begin ( Page page,
WriteMode  placement = e_overlay,
bool  compress = true 
)

Begin writing to the given page.

By default, new content will be appended to the page, as foreground graphics. It is possible to add new page content as background graphics by setting the second parameter in begin method to 'true' (e.g. writer.Begin(page, true)).

Parameters:
page The page to write content.
placement An optional flag indicating whether the new content should be added as a foreground or background layer to the existing page. By default, the new content will appear on top of the existing graphics.
compress An optional flag indicating whether the page content stream should be compressed. This may be useful for debugging content streams. Also some applications need to do a clear text search on strings in the PDF files. By default, all content streams are compressed.

void pdftron::PDF::ElementWriter::Begin ( const Page page,
bool  background,
bool  compress = true 
)

Begin writing to the given page.

By default, new content will be appended to the page, as foreground graphics. It is possible to add new page content as background graphics by setting the second parameter in begin method to 'true' (e.g. writer.Begin(page, true)).

Parameters:
page The page to write content.
background An optional flag indicating whether the new content should be added as a foreground or background layer to the existing page. If background is 'true', the graphics will be added in a background layer. By default, the new content will appear on top of the existing graphics.
compress An optional flag indicating whether the page content stream should be compressed. This may be useful for debugging content streams. Also some applications need to do a clear text search on strings in the PDF files. By default, all content streams are compressed.

void pdftron::PDF::ElementWriter::Begin ( SDF::SDFDoc doc,
bool  compress = true 
)

Begin writing an Element sequence to a new stream.

Use this function to write Elements to a content stream other than the page. For example, you can create Form XObjects (See Section '4.9 Form XObjects' in PDF Reference for more details) pattern streams, Type3 font glyph streams, etc.

Parameters:
doc - A low-level SDF/Cos document that will contain the new stream. You can access low-level document using PDFDoc::GetSDFDoc() or Obj::GetDoc() methods.
compress An optional flag indicating whether the page content stream should be compressed. This may be useful for debugging content streams. Also some applications need to do a clear text search on strings in the PDF files. By default, all content streams are compressed.
Note:
the newly created content stream object is returned when writing operations are completed (i.e. after the call to ElementWriter::End()).

void pdftron::PDF::ElementWriter::Begin ( SDF::Obj  stream_obj_to_update,
bool  compress = true 
)

Begin writing an Element sequence to a stream.

Use this function to write Elements to a content stream which will replace an existing content stream in an object passed as a parameter.

Parameters:
stream_obj_to_update - A low-level SDF stream object that will contain the new stream. Old stream inside that object will be discarded.
compress An optional flag indicating whether the content stream should be compressed. This may be useful for debugging content streams. Also some applications need to do a clear text search on strings in the PDF files. By default, all content streams are compressed.
Note:
The content stream object is returned when writing operations are completed (i.e. after the call to ElementWriter::End()).

SDF::Obj pdftron::PDF::ElementWriter::End (  ) 

Finish writing to a page.

Returns:
A low-level stream object that was used to store Elements.

void pdftron::PDF::ElementWriter::WriteElement ( Element  element  ) 

Writes the Element to the content stream.

void pdftron::PDF::ElementWriter::WritePlacedElement ( Element  element  ) 

A utility function that surrounds the given Element with a graphics state Save/Restore Element (i.e.

in PDF content stream represented as 'q element Q').

The function is equivalent to calling WriteElement three times: WriteElement(eSave); WriteElement(element); WriteElement(eRestore);

where eSave is 'e_group_begin' and eRestore is 'e_group_end' Element

The function is useful when XObjects such as Images and Forms are drawn on the page.

void pdftron::PDF::ElementWriter::Flush (  ) 

The Flush method flushes all pending Element writing operations.

This method is typically only required to be called when intermixing direct content writing (i.e. WriteBuffer/WriteString) with Element writing.

void pdftron::PDF::ElementWriter::WriteBuffer ( const char *  data,
int  data_sz 
)

Writes an arbitrary buffer to the content stream.

This function can be used to insert comments, inline-image data, and chunks of arbitrary content to the output stream.

void pdftron::PDF::ElementWriter::WriteString ( const char *  str  ) 

Writes an arbitrary string to the content stream.

Serves the same purpose as WriteBuffer().


© 2002-2010 PDFTron Systems Inc.