TPrinter - Read Write Edit and View Documents

TPrinter - Read Write Edit and View Documents
REQUEST FOR COMMENTS

RFC: OPDC-Printer-2018-10-01-0000-0001

Open Printer and Document Consortium (OPDC)
J. Hecht
Code4Sale, LLC
121 Louise Dr, Crestview, FL 32636 U.S.A.
https://code4sale.com/opdc


Reply at: https://code4sale.com/email/OPDC


Open DocumentPrinter and PageCanvas API Specification 1.0


Copyright ©2018 by Joe C. Hecht - All rights reserved.


Introduction


A language independent open API for Virtual Printer and Canvas objects, for the general purpose of reading, writing, editing, conversion, and viewing of most document formats.


History


OPDC-Printer-2018-10-01-0000-0001 : Initial draft proposal



Overview


The printer and canvas objects and APIs (as used by developers) have served well at the job of encapsulating the chore of printing.

Given the common drawing API used by a printer canvas, in today's world of virtual printers (such as print to PDF), these 'write only' objects can be
easily extended to have both 'read' and 'write' capabilities, allowing these
APIs to serve as ideal containers to easily append, edit, convert and even
display document pages using a common interface.

Consider a 'PDF' document as printed from a vendor's implementation of a printer API (such as Microsoft Windows® or the Delphi® 'TPrinter' object.

If the vendor implemented a 'read write' version of the API, the BeginDoc()
call could be extended to accept (for example) a PDF file as an input document.

The document could then have new pages appended to it, the pages could have new content added (or content edited), and the document could be easy manipulated (providing document assembly services).

Given a common API, previously printed documents can be reliably opened, edited, appended, converted, and viewed.

Simplification and enhancing the security of current document formats is also possible. The PDF format is a very good example. PDF documents can be very complex, and present many security challenges. While the PDF specification is large, even the most complex PDF pages can be 'distilled' down to a basic (and common) drawing API consisting of simple lines, paths, text, images, and clipping, that can easily be edited (and then distributed securely).

The Open Printer and Document Consortium (OPDC) wants to deliver a simple, common API that developers can easily use, that can be easily implemented in any language, on any platform, to create, append, edit, convert and display documents of high fidelity.

Vendors are free to choose the document format they wish to support.

This simple, and common API is vendor extend-able, (via an SDK property) that can expose a vendors specific SDK API interface (that is not common to the OPDC API), allowing developer toolkits to provide direct access their specific toolkit, API, functions, methods, and properties in a (vendor supplied) independent manor, though the OPDC Printer interface.

OPDC Printer and Canvas Implementation examples are to be provided from OPDC in both 'object orientated' form, and in a function based (non object orientated) API.

To be a compliant OPDC Printer and Canvas Implementation, a vendor must simply follow the API interface and be able to 'read back what they have written' via the API the OPDC API interface.

OPDC is proud to announce that the first vendor implementation is now under OPDC testing for eventual certification, and is due for retail shipment in early October as put forth by http://UberPDF.org (ahead of our finalized version 1.0 specification).

OPDC invites comments and suggestions to the specification, and is soliciting both roles of sponsorship and members of leadership for our steering committee.


Copyright: Our API is copyrighted. To make a OPDC API derivative implementation, you must provide the official OPDC copyright notice in the OPDC API portion of your implementation. Your specific implementation (your code) is yours to copyright. We will most likely release the final specification under a creative commons license.



COMMON OPDC Printer - Functional API Version 1.0 Draft - (object interface)


All functions return a simple boolean value, indicating success (true), or
failure (false). Vendor specific error codes may be provided via the
GetLastError() method.

Pages are numbered one through Printer.PageCount. A page number input parameter of zero is generally considered to mean 'the beginning of the document' (the same as one). Page numbers greater than the Printer.PageCount are generally considered to mean 'the end of the document'.

Measurement values (parameters and properties) have been specially crafted for the purpose of working with documents using industry standard measurements (such as pixels, points, picas, inches, centimeters, and millimeters) in a convenient manor.

A 'pixelsPerInch' property exists to facilitate conversion between measurements.

The OPDC Printer and Canvas objects provide a settable 'MeasureMode' property that states the measurement system the developer currently desires to work with.

MeasureMode(Pixels) uses a traditional 'top down' origin where (0,0) is at top left of the page and y values increase toward the bottom of the page. Rectangle members are specified in the traditional order of 'Left, Top, Right, Bottom'.

MeasureMode(points, picas, inches, centimeters, and millimeters) use a
'bottom up' Cartesian coordinate origin (traditional to document professionals) where (0,0) is at the bottom left of the page and y values increase toward the top of the page. Rectangle members are specified in the traditional order of 'Left, Bottom, Right, Top'.

The internal storage format of measurements is left to the vendor. Conversion functions are provided for the standard MeasureModes provided.

Most (applicable) measurements are passed and returned (by value) using floating point values. Functions taking rectangle structures (where required) are provided in both integer and floating point versions (for the convenience of the developer).

An OPDC printer object has the concept of a Canvas object (used to draw output to a page). The Canvas object has the concept of a current Pen, Brush, and Font.

As the developer navigates the pages of the document, the page canvas (to draw with) is generally made available to the developer. The page canvas may also be used as a readable source canvas. Pages may be locked with a read only flag. Creation of a page canvas is left to the vendor. To maximize performance a vendor may choose to create the canvas only upon the actual access of the Canvas property.

Like the Printer object, the Canvas, Pen, Brush, and Font objects each have a settable 'MeasureMode' property that states the measurement system the developer currently desires to work with. Upon the creation of the canvas (and associated objects), the MeasureMode of those objects is initialized with the current MeasureMode of the printer.

The default MeasureMode for font objects have a separate property in the Printer object, since it is common for developers to work in one MeasureMode (such as inches) for the document, and want to specify font measurements using a different MeasureMode (such as points).

The OPDC Canvas object API specification (along with the Pen, Brush, and Font API) will be provided in a separate RFC document.




OPDC Printer Public Properties


Printer.DefaultMediaWidth(float): The current width used for newly created pages.

Printer.DefaultMediaHeight(float): The current height used for newly created pages.

Printer.DefaultMediaRotation(int): The current clockwise rotation used for newly created pages, in 90 degree increments (minimum value: 0; maximum value: 270).

Printer.DefaultPixelsPerInch(float): The current, non-zero, positive
PixelsPerInch used for newly created pages.

Printer.MeasureMode(TMeasureMode): The current MeasureMode;

Printer.FontMeasureMode(TMeasureMode): The current MeasureMode used for fonts;

Printer.MediaWidth(float): [read only] The MediaWidth of the current page.

Printer.MediaHeight(float): [read only] The MediaHeight of the current page.

Printer.MediaRotation(int): [read only] The MediaRotation of the current page.

Printer.PageCount: [read only] The page count of the document.

Printer.PageNumber: [read only] The current page number in the document.

Printer.Canvas: [read only] The Canvas for the current page.

Printer.SDK: [read only] The vendor specific SDK API.

Printer.Title: the title of the document (use is vendor Specific).

Printer.Aborted: [read only] true if Printer.AbortDoc() has been called for the current document.

Printer.Printing: [read only] true when Printer.BeginDoc(), Printer.OpenDoc() or like function has been called, and before Printer.EndDoc or Printer.Aborted has been called.

Printer.Orientation(int): If the current page is portrait or landscape (or if
newly created pages will be portrait or landscape. A vendor specific
implementation, with the recommendation that 'Portrait' will set the
Printer.MediaRotation and Printer.DefaultMediaRotation to zero, and 'Landscape' will set the Printer.MediaRotation and Printer.DefaultMediaRotation to 90.

Printer.Copies(int): Vendor specific. In general, virtual document printers do not support copies. Default value: 1.

Printer.Handle: Vendor specific.

Printer.Capabilities(enum): [Copies, Orientation, Collation]. Vendor specific.

Printer.Printers(list): Language dependent, Vendor specific implementation.

Printer.Fonts(list): Language dependent, Vendor specific implementation.



OPDC Printer Functions



Function Printer.Create(); Creates and initializes an OPDC Printer and Canvas Object Implementation, and prepares to create a new document, or to open an existing document. Printer.DefaultMediaWidth, Printer.DefaultMediaHeight, and Printer.DefaultMediaRotation are set to default values (and used for newly created pages). Developers may update the default values used for media sizes and media rotations at any time (before new pages are created).


Function Printer.BeginDoc(); Creates a new document containing one (empty) page. The OPDC Canvas Object is ready to draw to. OPDC documents must always contain at least one valid page. The media size and media rotation of the new page are taken from the current default values as set in Printer object. The Printer.PageCount and the Printer.PageNumber are set to one. If the Printer object already contains a document, the printer object's existing document is discarded (as though Printer.Abort() had been called).


Function Printer.OpenDoc('Existing_Document'); Opens an existing, vendor supported document. The document must contain at least one valid page (else an error value is returned). The Printer.PageCount property is initialized. The Printer.PageNumber is set to the first page. The OPDC Canvas Object is initialized, and is to ready draw to page one. If the Printer object already contains a document, the printer object's existing document is discarded (as though Printer.Abort() had been called).


Function Printer.AppendDoc('Existing_Document'); Opens an existing, vendor supported document. The document must contain at least one valid page (else an error value is returned). A new empty page is appended to the end of the document. The Printer.PageCount property is initialized, and the Printer.PageNumber is set to newly created page that has been appended the end of the document. The OPDC Canvas Object is initialized, and is to ready draw to the appended last page. If the Printer object already contains a document, the printer object's existing document is discarded (as though Printer.Abort() had been called).


Function Printer.OpenDocFromMemory(buffer, size); provides the same
functionality as Printer.OpenDoc(), but loads the document from a memory buffer.


Function Printer.OpenDocFromStream(stream); provides the same functionality as Printer.OpenDoc(), but loads the document from a stream. Language specific.


Function Printer.AppendDocFromMemory(buffer, size); provides the same functionality as Printer.AppendDoc(), but loads the document from a memory buffer.


Function Printer.AppendDocFromStream(stream); provides the same functionality as Printer.AppendDoc(), but loads the document from a stream. Language specific.


Function Printer.GotoPage(PageNumber); The OPDC Canvas Object is finalized for the current page, Printer.PageNumber is set to PageNumber. Pages are numbered 'one through PageCount'. If the PageNumber provided is equal to Printer.PageNumber (the current page) nothing is done (and a success value is returned). A PageNumber of zero is considered to be equal to 'go to the beginning of the document' IE Printer.GotoPage(1). If the PageNumber provided is greater than the document PageCount, new empty pages are appended to the end of the document to enable achieving PageNumber (and Printer.PageCount is
incremented accordingly). The page is advanced to PageNumber and
Printer.PageNumber is updated. The OPDC Canvas Object is initialized, and is ready draw on the page.


Function Printer.NewPage(); The OPDC Canvas Object is finalized for the current page, and a new page is created and inserted at (Printer.PageNumber + 1). The Printer.PageNumber and Printer.PageCount properties are incremented. The OPDC Canvas Object is initialized, and is to ready draw to the new page.


Function Printer.NextPage(); The OPDC Canvas Object is finalized for the current page. If at the end of document, a new blank page is appended to the end of the document. The Printer.PageNumber is advanced. The OPDC Canvas Object is initialized, and is to ready draw to the page.


Function Printer.InsertPage(); The OPDC Canvas Object is finalized for the current page. A new page is created and inserted at (before) the current page. The Printer.PageNumber property is not changed (since the newly inserted page is now at the same page number location). Printer.PageCount is incremented. The OPDC Canvas Object is initialized for the inserted page and is ready to draw.


Function Printer.DeletePage(); The OPDC Canvas Object is finalized for the current page, and the current page is deleted. Printer.PageCount is decremented. If the document becomes empty, a new blank page is created (and becomes the current page). If at end of document, the current page will be the previous page in the document (prior to deletion), else the current page will be the next page in the document (prior to deletion). The OPDC Canvas Object is initialized for the new current page and is ready to draw.


Function Printer.MovePage(BeforePageNumber); The OPDC Canvas Object is finalized for the current page, and the current page is removed and inserted at BeforePageNumber. If BeforePageNumber is zero, BeforePageNumber behaves like it is one (moving page to the beginning of the document). If BeforePageNumber is greater than Printer.PageCount, the page is moved to the end of the document. If BeforePageNumber is equal to Printer.PageNumber, nothing is done, and a success code is returned. After the move, Printer.PageNumber stays the same, however the page at Printer.PageNumber changes. If the page was moved to a location earlier in the document, the new current page will be the previous page (before the page was moved). If the page was moved to a location later in the document, the new current page will be the next page (before the page was moved). The OPDC Canvas Object is initialized for the new current page and is ready to draw.


Function Printer.ImportPage(SrcPrinter, SrcPageNumber, InsertBeforePageNumber); If SrcPrinter, or SrcPageNumber is not valid, an error code is returned. The OPDC Canvas Object is finalized for the current page. The page at SrcPageNumber is imported from SrcPrinter and inserted at (before) the page indicated in the InsertBeforePageNum er parameter. If InsertBeforePageNumber is zero, it is considered to be the same as page one (insert at the beginning of the document). If InsertBeforePageNumber is greater than Printer.PageCount, the imported page is appended to the end of the document. On success the Printer.PageCount is incremented. After the import, the current page stays the same, however, the Printer.PageNumber may change if InsertBeforePageNumber is equal to or less than the Printer.PageNumber before the import. The OPDC Canvas Object is initialized for the current page and is ready to draw. It is reasonable for vendors to document that SrcPrinter should remain open (and in a locked read only state) until the destination printer has written the resulting document.


Function Printer.ReleasePage(); The OPDC Canvas Object is finalized for the current page, allowing the developer to use vendor specific SDK functions to access and manipulate the document. After such manipulations, developers should call the Printer.Refresh() method to allow the printer object to reinitialize with any changes made to the document. After calling a Printer.ReleasePage() and Printer.Refresh() sequence, the value of the current page may change (perhaps the page no longer exists). If the page does change, the expected behavior for the current page is to be documented by the vendor. The generally
expected behavior is for the current page not to change. The OPDC specification states that at least one valid document page must exist for document operations to continue. The OPDC Canvas Object should always be prepared to initialize itself for the current page, and be ready to draw on the first canvas access.


Function Printer.Refresh(); The OPDC Canvas Object is finalized (if needed) for the current page, and the Printer object is reinitialized from the document. Developers (and vendors) may use vendor specific SDK functions to access and manipulate the document. After using such manipulations, developers should call the Printer.Refresh() method to allow the printer object to reinitialize to any changes made to the document. After calling Printer.Refresh(), the value of the current page may change (perhaps the page no longer exists). If the page does change, the expected behavior for the current page is to be documented by the vendor. The generally expected behavior is for the current page not to
change. The OPDC specification states that at least one valid document page must exist for document operations to continue. The OPDC Canvas Object should always be prepared to initialize itself for the current page, and be ready to draw on the first canvas access.


Function Printer.Abort(); The OPDC Canvas Object is finalized (if needed) for the current page, and the document is discarded. The Printer object will either be destroyed, or initialized for a new document via a call to BeginDoc(), OpenDoc(), or similar function.


Function Printer.EndDoc(FileName); The OPDC Canvas Object is finalized for the current page, the document is finalized and saved to FileName, and the Printer object will either be destroyed, or initialized for a new document via a call to BeginDoc(), OpenDoc(), or similar function.


Function Printer.GetLastError(int); Provides a vendor specific error code
containing the last error. Default value: zero.

[END RFC: OPDC-2018-10-01-0000-0001]


Product names, trademarks, and servicemarks mentioned are owned by their respective owners.