PTElementBuilder

@interface PTElementBuilder : NSObject

ElementBuilder is used to build new PDF::Elements (e.g. image, text, path, etc) from scratch. In conjunction with ElementWriter, ElementBuilder can be used to create new page content.

Note

Analogous to ElementReader, every call to ElementBuilder.Create? method destroys the Element currently associated with the builder and all previous Element pointers are invalidated.

Note

For C++ developers. Analogous to ElementReader, ElementBuilder is the owner of all Element objects it creates.

  • The function sets the graphics state of this Element to the given value. If ‘gs’ parameter is not specified or is NULL the function resets the graphics state of this Element to the default graphics state (i.e. the graphics state at the beginning of the display list).

    The function can be used in situations where the same ElementBuilder is used to create content on several pages, XObjects, etc. If the graphics state is not Reset() when moving to a new display list, the new Element will have the same graphics state as the last Element in the previous display list (and this may or may not be your intent).

    Another use of Reset(gs) is to make sure that two Elements have the graphics state.

    Declaration

    Objective-C

    - (void)Reset:(PTGState *)gs;

    Swift

    func reset(_ gs: PTGState!)

    Parameters

    gs

    GState (graphics state) object. If NULL or unspecified, resets graphics state to default.

  • Create a content image Element out of a given document Image.

    Declaration

    Objective-C

    - (PTElement *)CreateImage:(PTImage *)img;

    Swift

    func createImage(_ img: PTImage!) -> PTElement!

    Parameters

    img

    the given image.

  • Create a content image Element out of a given document Image.

    Declaration

    Objective-C

    - (PTElement *)CreateImageWithMatrix:(PTImage *)img mtx:(PTMatrix2D *)mtx;

    Swift

    func createImage(withMatrix img: PTImage!, mtx: PTMatrix2D!) -> PTElement!

    Parameters

    img

    the given image.
    mtx

    the image transformation matrix.

  • Create a content image Element out of a given document Image with the lower left corner at (x, y), and scale factors (hscale, vscale).

    Declaration

    Objective-C

    - (PTElement *)CreateImageWithCornerAndScale:(PTImage *)img
                                           x:(double)x
                                           y:(double)y
                                      hscale:(double)hscale
                                      vscale:(double)vscale;

    Swift

    func createImage(withCornerAndScale img: PTImage!, x: Double, y: Double, hscale: Double, vscale: Double) -> PTElement!

    Parameters

    img

    the given image.
    x

    The horizontal x position to place the lower left corner of the image
    y

    The vertical x position to place the lower left corner of the image
    hscale

    The horizontal scale of the image
    vscale

    The vertical scale of the image

  • Create e_group_begin Element (i.e. ‘q’ operator in PDF content stream). The function saves the current graphics state.

    Declaration

    Objective-C

    - (PTElement *)CreateGroupBegin;

    Swift

    func createGroupBegin() -> PTElement!

  • Create e_group_end Element (i.e. ‘Q’ operator in PDF content stream). The function restores the previous graphics state.

    Declaration

    Objective-C

    - (PTElement *)CreateGroupEnd;

    Swift

    func createGroupEnd() -> PTElement!

  • Declaration

    Objective-C

    - (PTElement *)CreateShading:(PTShading *)sh;

    Swift

    func createShading(_ sh: PTShading!) -> PTElement!

    Parameters

    sh

    A Shading object. Shading objects represent a flat interface around all PDF shading types (e_function_shading, e_axial_shading, etc.) Create a shading Element.

  • Create a Form XObject Element.

    Declaration

    Objective-C

    - (PTElement *)CreateFormWithObj:(PTObj *)form;

    Swift

    func createForm(with form: PTObj!) -> PTElement!

    Parameters

    form

    a Form XObject content stream

  • Create a Form XObject Element using the content of the existing page. This method assumes that the XObject will be used in the same document as the given page. If you need to create the Form XObject in a different document use CreateForm(Page, Doc) method.

    Declaration

    Objective-C

    - (PTElement *)CreateFormWithPage:(PTPage *)page;

    Swift

    func createForm(with page: PTPage!) -> PTElement!

    Parameters

    page

    A page used to create the Form XObject.

  • Create a Form XObject Element using the content of the existing page. Unlike CreateForm(Page) method, you can use this method to create form in another document.

    Declaration

    Objective-C

    - (PTElement *)CreateFormWithPageAndDestination:(PTPage *)page
                                            doc:(PTPDFDoc *)doc;

    Swift

    func createForm(withPageAndDestination page: PTPage!, doc: PTPDFDoc!) -> PTElement!

    Parameters

    page

    A page used to create the Form XObject.
    doc

    Destination document for the Form XObject.

  • Start a text block (‘BT’ operator in PDF content stream). The function installs the given font in the current graphics state.

    Declaration

    Objective-C

    - (PTElement *)CreateTextBeginWithFont:(PTFont *)font font_sz:(double)font_sz;

    Swift

    func createTextBegin(with font: PTFont!, font_sz: Double) -> PTElement!

    Parameters

    font

    font to set the text in the text block to
    font_sz

    size to set the text in the text block to

  • Start a text block (‘BT’ operator in PDF content stream).

    Declaration

    Objective-C

    - (PTElement *)CreateTextBegin;

    Swift

    func createTextBegin() -> PTElement!

  • Ends a text block.

    Declaration

    Objective-C

    - (PTElement *)CreateTextEnd;

    Swift

    func createTextEnd() -> PTElement!

  • Create a text run using the given font.

    Note

    a text run can be created only within a text block

    Declaration

    Objective-C

    - (PTElement *)CreateTextRunWithFont:(NSString *)text_data
                                font:(PTFont *)font
                             font_sz:(double)font_sz;

    Swift

    func createTextRun(withFont text_data: String!, font: PTFont!, font_sz: Double) -> PTElement!

  • Create a new text run.

    Note

    a text run can be created only within a text block

    Note

    you must set the current Font and font size before calling this function.

    Declaration

    Objective-C

    - (PTElement *)CreateTextRun:(NSString *)text_data;

    Swift

    func createTextRun(_ text_data: String!) -> PTElement!

  • Create a new Unicode text run.

    Note

    you must set the current Font and font size before calling this function and the font must be created using Font::CreateCIDTrueTypeFont() method.

    Note

    a text run can be created only within a text block

    Declaration

    Objective-C

    - (PTElement *)CreateUnicodeTextRun:(unsigned short *)text_data
                       text_data_sz:(unsigned int)text_data_sz;

    Swift

    func createUnicodeTextRun(_ text_data: UnsafeMutablePointer<UInt16>!, text_data_sz: UInt32) -> PTElement!

    Parameters

    text_data

    pointer to Unicode text
    text_data_sz

    number of characters (not bytes) in text_data

  • Create a new text run from shaped text. Shaped Text can be created with an approriate Font, using the Font::GetShapedText() method.

    Note

    you must set the current Font and font size before calling this function and the font must be created using Font::CreateCIDTrueTypeFont() method, and should be the same font used to generate the shaped text content.

    Note

    For best results, the font should be encoded using the e_Indices encoding scheme.

    Note

    a text run can be created only within a text block

    Declaration

    Objective-C

    - (PTElement *)CreateShapedTextRun:(PTShapedText *)text_data;

    Swift

    func createShapedTextRun(_ text_data: PTShapedText!) -> PTElement!

    Parameters

    text_data

    the shaped text data

  • Create e_text_new_line Element (i.e. a Td operator in PDF content stream). Move to the start of the next line, offset from the start of the current line by (dx , dy). dx and dy are numbers expressed in unscaled text space units.

    Declaration

    Objective-C

    - (PTElement *)CreateTextNewLineWithOffset:(double)dx dy:(double)dy;

    Swift

    func createTextNewLine(withOffset dx: Double, dy: Double) -> PTElement!

    Parameters

    dx

    The horizontal x offset from the start of the current line
    dy

    The vertical y offset from the start of the current line

    Return Value

    the path Element

  • Create e_text_new_line Element (i.e. a T* operator in PDF content stream).

    Declaration

    Objective-C

    - (PTElement *)CreateTextNewLine;

    Swift

    func createTextNewLine() -> PTElement!

    Return Value

    the path Element

  • Create a path Element using given path segment data

    Declaration

    Objective-C

    - (PTElement *)CreatePath:(NSMutableArray *)points
                seg_types:(NSData *)seg_types;

    Swift

    func createPath(_ points: NSMutableArray!, seg_types: Data!) -> PTElement!

    Return Value

    the path Element

  • Create a rectangle path Element.

    Declaration

    Objective-C

    - (PTElement *)CreateRect:(double)x
                        y:(double)y
                    width:(double)width
                   height:(double)height;

    Swift

    func createRect(_ x: Double, y: Double, width: Double, height: Double) -> PTElement!

    Parameters

    x

    The horizontal coordinate of the lower left corner of the rectangle.
    y

    The vertical coordinate of the lower left corner of the rectangle.
    width

    The width of the rectangle.
    height

    The height of the rectangle.

    Return Value

    the path Element

  • Create an ellipse (or circle, if width == height) path Element.

    Declaration

    Objective-C

    - (PTElement *)CreateEllipse:(double)x
                           y:(double)y
                       width:(double)width
                      height:(double)height;

    Swift

    func createEllipse(_ x: Double, y: Double, width: Double, height: Double) -> PTElement!

    Parameters

    x

    The horizontal x coordinate of the ellipse center.
    y

    The vertical y coordinate of the ellipse center.
    width

    The width of the ellipse rectangle.
    height

    The height of the ellipse rectangle.

    Return Value

    the path Element

  • Starts building a new path Element that can contain an arbitrary sequence of lines, curves, and rectangles.

    Declaration

    Objective-C

    - (void)PathBegin;

    Swift

    func pathBegin()

  • Finishes building of the path Element.

    Declaration

    Objective-C

    - (PTElement *)PathEnd;

    Swift

    func pathEnd() -> PTElement!

    Return Value

    the path Element

  • Set the current point.

    Declaration

    Objective-C

    - (void)MoveTo:(double)x y:(double)y;

    Swift

    func move(to x: Double, y: Double)

    Parameters

    x

    The horizontal x component of the point
    y

    The vertical y component of the point

  • Draw a line from the current point to the given point.

    Declaration

    Objective-C

    - (void)LineTo:(double)x y:(double)y;

    Swift

    func line(to x: Double, y: Double)

    Parameters

    x

    The horizontal x component of the goal point
    y

    The vertical y component of the goal point

  • Draw a Bezier curve from the current point to the given point (x2, y2) using (cx1, cy1) and (cx2, cy2) as control points.

    Declaration

    Objective-C

    - (void)CurveTo:(double)cx1
            cy1:(double)cy1
            cx2:(double)cx2
            cy2:(double)cy2
             x2:(double)x2
             y2:(double)y2;

    Swift

    func curve(to cx1: Double, cy1: Double, cx2: Double, cy2: Double, x2: Double, y2: Double)

    Parameters

    cx1

    The x component of the first control point
    cy1

    The y component of the first control point
    cx2

    The x component of the second control point
    cy2

    The y component of the second control point
    x2

    The horizontal x component of the goal point
    y2

    The vertical y component of the goal point

  • Draw an arc with the specified parameters (lower left corner, width, height and angles).

    Declaration

    Objective-C

    - (void)ArcToWithParam:(double)x
                     y:(double)y
                 width:(double)width
                height:(double)height
                 start:(double)start
                extent:(double)extent;

    Swift

    func arcTo(withParam x: Double, y: Double, width: Double, height: Double, start: Double, extent: Double)

    Parameters

    x

    The horizontal x coordinate of the lower left corner of the ellipse encompassing rectangle
    y

    The horizontal y coordinate of the lower left corner of the ellipse encompassing rectangle
    width

    overall width of the full ellipse (not considering the angular extents).
    height

    overall height of the full ellipse (not considering the angular extents).
    start

    starting angle of the arc in degrees
    extent

    angular extent of the arc in degrees

  • Draw an arc from the current point to the end point.

    Note

    The Arc is defined the same way as it is specified by SVG or XPS standards. For further questions please refer to the XPS or SVG standards.

    Declaration

    Objective-C

    - (void)ArcToEndPt:(double)xr
                yr:(double)yr
                rx:(double)rx
        isLargeArc:(BOOL)isLargeArc
             sweep:(BOOL)sweep
              endX:(double)endX
              endY:(double)endY;

    Swift

    func arc(toEndPt xr: Double, yr: Double, rx: Double, isLargeArc: Bool, sweep: Bool, endX: Double, endY: Double)

    Parameters

    xr

    x radius for the arc
    yr

    y radius for the arc
    rx

    x-axis rotation in radians
    isLargeArc

    indicates if smaller or larger arc is chosen 1 - one of the two larger arc sweeps is chosen 0 - one of the two smaller arc sweeps is chosen
    sweep

    direction in which arc is drawn (1 - clockwise, 0 - counterclockwise)
    endX

    x coordinate of end point
    endY

    y coordinate of end point

  • Add an ellipse (or circle, if rx == ry) to the current path as a complete subpath. Setting the current point is not required before using this function.

    Declaration

    Objective-C

    - (void)Ellipse:(double)x y:(double)y width:(double)width height:(double)height;

    Swift

    func ellipse(_ x: Double, y: Double, width: Double, height: Double)

    Parameters

    x

    The x coordinate of the ellipse center.
    y

    The y coordinate of the ellipse center.
    width

    The x radii of the ellipse.
    height

    The y radii of the ellipse.

  • Add a rectangle to the current path as a complete subpath. Setting the current point is not required before using this function.

    Declaration

    Objective-C

    - (void)Rect:(double)x y:(double)y width:(double)width height:(double)height;

    Swift

    func rect(_ x: Double, y: Double, width: Double, height: Double)

    Parameters

    x

    The x coordinate of the lower left corner of the rectangle.
    y

    The y coordinate of the lower left corner of the rectangle.
    width

    The width of the rectangle.
    height

    The height of the rectangle.

  • Closes the current subpath.

    Declaration

    Objective-C

    - (void)ClosePath;

    Swift

    func closePath()

  • Create e_marked_content_begin element with an inline property dictionary (i.e. BDC operator in PDF content stream).

    Note

    The inline property dictionary can be accessed and edited using element.GetMCPropertyDict()

    Declaration

    Objective-C

    - (PTElement *)CreateMarkedContentBeginInlineProperties:(NSString *)tag;

    Swift

    func createMarkedContentBeginInlineProperties(_ tag: String!) -> PTElement!

    Parameters

    tag

    the tag entry for this element.

    Return Value

    the marked content begin element.

  • Create e_marked_content_begin element with an associated property dictionary (i.e. BMC or BDC operator in PDF content stream).

    Declaration

    Objective-C

    - (PTElement *)CreateMarkedContentBegin:(NSString *)tag
                          property_dict:(PTObj *)property_dict;

    Swift

    func createMarkedContentBegin(_ tag: String!, property_dict: PTObj!) -> PTElement!

    Parameters

    tag

    the tag entry for this element.
    property_dict

    the property dictionary.

    Return Value

    the marked content begin element.

  • Create e_marked_content_end element (i.e. EMC operator in PDF content stream).

    Declaration

    Objective-C

    - (PTElement *)CreateMarkedContentEnd;

    Swift

    func createMarkedContentEnd() -> PTElement!

    Return Value

    the marked content end element.

  • Create e_marked_content_point element with an inline property dictionary (i.e. DP operator in PDF content stream).

    Note

    The inline property dictionary can be accessed and edited using element.GetMCPropertyDict()

    Declaration

    Objective-C

    - (PTElement *)CreateMarkedContentPointInlineProperties:(NSString *)tag;

    Swift

    func createMarkedContentPointInlineProperties(_ tag: String!) -> PTElement!

    Parameters

    tag

    the tag entry for this element.

    Return Value

    the marked content point element.

  • Create e_marked_content_point element with an associated property dictionary (i.e. MP or DP operator in PDF content stream).

    Declaration

    Objective-C

    - (PTElement *)CreateMarkedContentPoint:(NSString *)tag
                          property_dict:(PTObj *)property_dict;

    Swift

    func createMarkedContentPoint(_ tag: String!, property_dict: PTObj!) -> PTElement!

    Parameters

    tag

    the tag entry for this element.
    property_dict

    the property dictionary.

    Return Value

    the marked content point element.

  • Undocumented

    Declaration

    Objective-C

    - (instancetype)init;

    Swift

    init!()

Additions

  • Creates a path element with the information from the specified bezier path.

    In addition to the points comprising the path data, the line width, line cap style, line join style, miter limit, flatness, and even-odd-fill-rule properties of the bezier path are also applied to the graphics state of the path element.

    Declaration

    Objective-C

    - (nonnull PTElement *)CreatePathWithBezierPath:
    (nonnull UIBezierPath *)bezierPath;

    Swift

    func createPath(with bezierPath: UIBezierPath) -> PTElement

    Parameters

    bezierPath

    The bezier path from which to create a path element

    Return Value

    the resulting path element