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 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 degrees

    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()
  • Undocumented

    Declaration

    Objective-C

    - (instancetype)init;

    Swift

    init!()