PTElementReader

@interface PTElementReader : NSObject

ElementReader can be used to parse and process content streams. ElementReader provides a convenient interface used to traverse the Element display list of a page. The display list representing graphical elements (such as text-runs, paths, images, shadings, forms, etc) is accessed using the intrinsic iterator. ElementReader automatically concatenates page contents spanning multiple streams and provides a mechanism to parse contents of sub-display lists (e.g. forms XObjects and Type3 fonts).

A sample use case for ElementReader is given below:

 ...
 ElementReader reader;
 reader.Begin(page);
 for (Element element=reader.Next(); element; element = reader.Next()) // Read page contents
 {
   switch (element.GetType())   {
     case Element::e_path: { // Process path data...
         const double* data = element.GetPathPoints();
         int sz = element.GetPointCount();
     }
     break;
     case Element::e_text:
         // ...
     break;
   }
 }
 reader.End();

For a full sample, please refer to ElementReader and ElementReaderAdvTest sample projects.


                    
                    
                    -ReaderBeginWithPage:ocg_context:

Undocumented

Declaration

Objective-C

- (void)ReaderBeginWithPage: (PTPage*)page ocg_context:  (PTContext*)ocg_context;

Swift

func readerBegin(with page: PTPage!, ocg_context: PTContext!)


                    
                    
                    -Begin:

Begin processing a page.

Note

When page processing is completed, make sure to call ElementReader.End().

Declaration

Objective-C

- (void)Begin:(PTPage *)page;

Swift

func begin(_ page: PTPage!)

Parameters

`page`	A page to start processing.
`ocg_context`	An optional parameter used to specify the Optional Content (OC) Context that should be used when processing the page. When the OCG::Context is specified, Element::IsOCVisible() will return ‘true’ or ‘false’ depending on the visibility of the current Optional Content Group (OCG) and the states of flags in the given context.


                    
                    
                    -ReaderBeginWithSDFObj:resource_dict:ocg_context:

Undocumented

Declaration

Objective-C

- (void)ReaderBeginWithSDFObj: (PTObj*)content_stream resource_dict:  (PTObj*)resource_dict ocg_context:  (PTContext*)ocg_context;

Swift

func readerBegin(withSDFObj content_stream: PTObj!, resource_dict: PTObj!, ocg_context: PTContext!)

-Next
Note

Every call to ElementReader::Next() destroys the current Element. Therefore, an Element becomes invalid after subsequent ElementReader::Next() operation.
Declaration
Objective-C

- (PTElement *)Next;
Swift

func next() -> PTElement!
Return Value

a page Element or a ‘NULL’ element if the end of current-display list was reached. You may use GetType() to determine the type of the returned Element.
-Current
Note

Every call to ElementReader::Next() destroys the current Element. Therefore, an Element becomes invalid after subsequent ElementReader::Next() operation.
Declaration
Objective-C

- (PTElement *)Current;
Swift

func current() -> PTElement!
Return Value

the current Element or a ‘NULL’ Element. The current element is the one returned in the last call to Next().
-FormBegin
When the current element is a form XObject you have the option to skip form processing (by not calling FormBegin()) or to open the form stream and continue Element traversal into the form.

To open a form XObject display list use FormBegin() method. The Next() returned Element will be the first Element in the form XObject display list. Subsequent calls to Next() will traverse form’s display list until NULL is returned. At any point you can close the form sub-list using ElementReader::End() method. After the form display list is closed (using End()) the processing will return to the parent display list at the point where it left off before entering the form XObject.
Declaration
Objective-C

- (void)FormBegin;
Swift

func formBegin()


                    
                    
                    -PatternBegin:reset_ctm_tfm:

A method used to spawn the sub-display list representing the tiling pattern of the current element in the ElementReader. You can call this method at any point as long as the current element is valid.

To open a tiling pattern sub-display list use PatternBegin(pattern) method. The Next() returned Element will be the first Element in the pattern display list. Subsequent calls to Next() will traverse pattern’s display list until NULL is encountered. At any point you can close the pattern sub-list using ElementReader::End() method. After the pattern display list is closed, the processing will return to the parent display list at the point where pattern display list was spawned.

Declaration

Objective-C

- (void)PatternBegin:(BOOL)fill_pattern reset_ctm_tfm:(BOOL)reset_ctm_tfm;

Swift

func patternBegin(_ fill_pattern: Bool, reset_ctm_tfm: Bool)

Parameters

`fill_pattern`	If true, the filling pattern of the current element will be spawned; otherwise, the stroking pattern of the current element will be spawned. Note that the graphics state will be inherited from the parent content stream (the content stream in which the pattern is defined as a resource) automatically.
`reset_ctm_tfm`	An optional parameter used to indicate whether the pattern’s display list should set its initial CTM and transformation matrices to identity matrix. In general, we should leave it to be false.


                    
                    
                    -Type3FontBegin:resource_dict:

A method used to spawn a sub-display list representing a Type3 Font glyph. You can call this method at any point as long as the current element in the ElementReader is a text element whose font type is type 3.

To open a Type3 font sub-display list use Type3FontBegin() method. The Next() returned Element will be the first Element in the glyph’s display list. Subsequent calls to Next() will traverse glyph’s display list until NULL is returned. At any point you can close the glyph sub-list using ElementReader::End() method. After the glyph display list is closed, the processing will return to the parent display list at the point where glyph display list was spawned.

Declaration

Objective-C

- (void)Type3FontBegin:(PTCharData *)char_data
         resource_dict:(PTObj *)resource_dict;

Swift

func type3FontBegin(_ char_data: PTCharData!, resource_dict: PTObj!)

Parameters

`char_data`	The information about the glyph to process. You can get this information by dereferencing a CharIterator.
`resource_dict`	- An optional ‘/Resource’ dictionary parameter. If any glyph descriptions refer to named resources but Font Resource dictionary is absent, the names are looked up in the supplied resource dictionary.

-End
Close the current display list.

If the current display list is a sub-list created using FormBegin(), PatternBegin(), or Type3FontBegin() methods, the function will end the sub-list and will return processing to the parent display list at the point where it left off before entering the sub-list.
Declaration
Objective-C

- (BOOL)End;
Swift

func end() -> Bool
Return Value

true if the closed display list is a sub-list or false if it is a root display list.
-GetChangesIterator
Declaration
Objective-C

- (PTGSChangesIterator *)GetChangesIterator;
Swift

func getChangesIterator() -> PTGSChangesIterator!
Return Value

an iterator to the beginning of the list containing identifiers of modified graphics state attributes since the last call to ClearChangeList(). The list can be consulted to determine which graphics states were modified between two Elements. Attributes are ordered in the same way as they are set in the content stream. Duplicate attributes are eliminated.


                    
                    
                    -IsChanged:

Declaration

Objective-C

- (BOOL)IsChanged:(PTGStateAttribute)attrib;

Swift

func isChanged(_ attrib: PTGStateAttribute) -> Bool

Parameters


                                attrib

the GState attribute to test if it has been changed ClearChangeList().

Return Value

true if given GState attribute was changed since the last call to

-ClearChangeList
Clear the list containing identifiers of modified graphics state attributes. The list of modified attributes is then accumulated during a subsequent call(s) to ElementReader.Next().
Declaration
Objective-C

- (void)ClearChangeList;
Swift

func clearChangeList()


                    
                    
                    -AppendResource:

Declaration

Objective-C

- (void)AppendResource:(PTObj *)res;

Swift

func appendResource(_ res: PTObj!)

Parameters

res

resource dictionary for finding images, fonts, etc.


                    
                    
                    -GetFont:

Declaration

Objective-C

- (PTObj *)GetFont:(NSString *)name;

Swift

func getFont(_ name: String!) -> PTObj!

Parameters


                                name

string of the name of the SDF/Cos object to get

Return Value

SDF/Cos object matching the specified name in the current resource dictionary. For ‘Page’ the name is looked up in the page’s /Resources/ dictionary. For Form XObjects, Patterns, and Type3 fonts that have a content stream within page content stream the specified resource is first looked-up in the resource dictionary of the inner stream. If the resource is not found, the name is looked up in the outer content stream’s resource dictionary. The function returns NULL if the resource was not found.


                    
                    
                    -GetXObject:

Note

see ElementReader::GetFont

Declaration

Objective-C

- (PTObj *)GetXObject:(NSString *)name;

Swift

func getXObject(_ name: String!) -> PTObj!

Parameters


                                name

string of the name of the SDF/Cos object to get


                    
                    
                    -GetShading:

Note

see ElementReader::GetFont

Declaration

Objective-C

- (PTObj *)GetShading:(NSString *)name;

Swift

func getShading(_ name: String!) -> PTObj!

Parameters


                                name

string of the name of the SDF/Cos object to get


                    
                    
                    -GetColorSpace:

Note

see ElementReader::GetFont

Declaration

Objective-C

- (PTObj *)GetColorSpace:(NSString *)name;

Swift

func getColorSpace(_ name: String!) -> PTObj!

Parameters


                                name

string of the name of the SDF/Cos object to get


                    
                    
                    -GetPattern:

Note

see ElementReader::GetFont

Declaration

Objective-C

- (PTObj *)GetPattern:(NSString *)name;

Swift

func getPattern(_ name: String!) -> PTObj!

Parameters


                                name

string of the name of the SDF/Cos object to get


                    
                    
                    -GetExtGState:

Note

see ElementReader::GetFont

Declaration

Objective-C

- (PTObj *)GetExtGState:(NSString *)name;

Swift

func getExtGState(_ name: String!) -> PTObj!

Parameters


                                name

string of the name of the SDF/Cos object to get

-init
Undocumented
Declaration
Objective-C

- (instancetype)init;
Swift

init!()

PTAdditions


                    
                    
                    -EnumerateElementsUsingBlock:

Enumerate over the elements associated with this element reader. This element reader must have already been set up with a call to a “Begin” method.

Note

The PTElement instance passed into the block only exists for the duration of the block and is invalidated immediately after. For this reason, it is not safe to hold onto references to the element instance.

Declaration

Objective-C

- (void)EnumerateElementsUsingBlock:
    (nonnull void (^)(PTElement *_Nonnull))block;

Swift

func enumerateElements(_ block: (PTElement) -> Void)

Parameters


                                block

The block to execute for each element encountered in the content stream