From 9d480eefad9a4ee8f243f473dc369097340904bb Mon Sep 17 00:00:00 2001 From: Josh Bialkowski Date: Tue, 10 Jul 2012 16:25:23 -0400 Subject: [PATCH 1/2] Adding some doxygen comments to the API --- poppler/Annot.h | 2 + poppler/Link.h | 32 +++--- poppler/Object.h | 26 ++++- poppler/OutputDev.h | 53 +++++----- poppler/PDFDoc.h | 224 ++++++++++++++++++++++++++++++++++-------- poppler/PDFDocBuilder.h | 2 + poppler/Page.h | 248 +++++++++++++++++++++++++++++++++++++++++------ poppler/XRef.h | 50 ++++++--- 8 files changed, 502 insertions(+), 135 deletions(-) diff --git a/poppler/Annot.h b/poppler/Annot.h index 0d20cc7..1a5157b 100644 --- a/poppler/Annot.h +++ b/poppler/Annot.h @@ -471,6 +471,8 @@ private: // Annot //------------------------------------------------------------------------ +/// An object of this class stores a single annotation to a page in a PDF +/// document class Annot { friend class Annots; friend class Page; diff --git a/poppler/Link.h b/poppler/Link.h index 8e2df24..64476ed 100644 --- a/poppler/Link.h +++ b/poppler/Link.h @@ -44,36 +44,37 @@ class Annots; // LinkAction //------------------------------------------------------------------------ +/// Enumerates the types of a PDF hyper-reference (link) enum LinkActionKind { - actionGoTo, // go to destination - actionGoToR, // go to destination in new file - actionLaunch, // launch app (or open document) - actionURI, // URI - actionNamed, // named action - actionMovie, // movie action + actionGoTo, ///< go to destination + actionGoToR, ///< go to destination in new file + actionLaunch, ///< launch app (or open document) + actionURI, ///< URI + actionNamed, ///< named action + actionMovie, ///< movie action actionRendition, - actionSound, // sound action - actionJavaScript, // JavaScript action - actionOCGState, // Set-OCG-State action - actionUnknown // anything else + actionSound, ///< sound action + actionJavaScript, ///< JavaScript action + actionOCGState, ///< Set-OCG-State action + actionUnknown ///< anything else }; class LinkAction { public: - // Destructor. + /// Destructor. virtual ~LinkAction() {} - // Was the LinkAction created successfully? + /// Was the LinkAction created successfully? virtual GBool isOk() = 0; - // Check link action type. + /// Check link action type. virtual LinkActionKind getKind() = 0; - // Parse a destination (old-style action) name, string, or array. + /// Parse a destination (old-style action) name, string, or array. static LinkAction *parseDest(Object *obj); - // Parse an action dictionary. + /// Parse an action dictionary. static LinkAction *parseAction(Object *obj, GooString *baseURI = NULL); }; @@ -461,6 +462,7 @@ private: // Links //------------------------------------------------------------------------ +/// An object of this class stores a list of links (hyper-references) class Links { public: diff --git a/poppler/Object.h b/poppler/Object.h index c885d73..618f61f 100644 --- a/poppler/Object.h +++ b/poppler/Object.h @@ -109,6 +109,23 @@ enum ObjType { #define initObj(t) zeroUnion(); type = t #endif + +/// A union type, similar to boost::variant +/** + * An Object may be any one of the following + * * a boolean + * * an integer + * * a real number + * * a string + * * a name (???) + * * nothing / empty + * * an array of Object* + * * a dictionary (map of const char* -> Object*) + * * a reference to an object + * * a file stream + * * an error + * * an unsigned integer + */ class Object { public: // clear the anonymous union as best we can -- clear at least a pointer @@ -153,15 +170,16 @@ public: return obj; } - // If object is a Ref, fetch and return the referenced object. - // Otherwise, return a copy of the object. + /// If object is a Ref, fetch and return the referenced object. + /// Otherwise, return a copy of the object. Object *fetch(XRef *xref, Object *obj, int recursion = 0); - // Free object contents. + /// Free object contents. void free(); - // Type checking. + /// Type checking. ObjType getType() { return type; } + GBool isBool() { return type == objBool; } GBool isInt() { return type == objInt; } GBool isReal() { return type == objReal; } diff --git a/poppler/OutputDev.h b/poppler/OutputDev.h index 15af90a..a920962 100644 --- a/poppler/OutputDev.h +++ b/poppler/OutputDev.h @@ -20,7 +20,7 @@ // Copyright (C) 2009-2012 Thomas Freitag // Copyright (C) 2009, 2011 Carlos Garcia Campos // Copyright (C) 2009, 2012 Albert Astals Cid -// Copyright (C) 2010 Christian Feuersänger +// Copyright (C) 2010 Christian Feuers�nger // Copyright (C) 2012 Fabio D'Urso // // To see a description of the changes please see the Changelog file that @@ -67,6 +67,7 @@ class Function; // OutputDev //------------------------------------------------------------------------ +/// Interface for rendering backends class OutputDev { public: @@ -78,49 +79,49 @@ public: //----- get info about output device - // Does this device use upside-down coordinates? - // (Upside-down means (0,0) is the top left corner of the page.) + /// Does this device use upside-down coordinates? + /// (Upside-down means (0,0) is the top left corner of the page.) virtual GBool upsideDown() = 0; - // Does this device use drawChar() or drawString()? + /// Does this device use drawChar() or drawString()? virtual GBool useDrawChar() = 0; - // Does this device use tilingPatternFill()? If this returns false, - // tiling pattern fills will be reduced to a series of other drawing - // operations. + /// Does this device use tilingPatternFill()? If this returns false, + /// tiling pattern fills will be reduced to a series of other drawing + /// operations. virtual GBool useTilingPatternFill() { return gFalse; } - // Does this device support specific shading types? - // see gouraudTriangleShadedFill() and patchMeshShadedFill() + /// Does this device support specific shading types? + /// see gouraudTriangleShadedFill() and patchMeshShadedFill() virtual GBool useShadedFills(int type) { return gFalse; } - // Does this device use FillColorStop()? + /// Does this device use FillColorStop()? virtual GBool useFillColorStop() { return gFalse; } - // Does this device use drawForm()? If this returns false, - // form-type XObjects will be interpreted (i.e., unrolled). + /// Does this device use drawForm()? If this returns false, + /// form-type XObjects will be interpreted (i.e., unrolled). virtual GBool useDrawForm() { return gFalse; } - // Does this device use beginType3Char/endType3Char? Otherwise, - // text in Type 3 fonts will be drawn with drawChar/drawString. + /// Does this device use beginType3Char/endType3Char? Otherwise, + /// text in Type 3 fonts will be drawn with drawChar/drawString. virtual GBool interpretType3Chars() = 0; - // Does this device need non-text content? + /// Does this device need non-text content? virtual GBool needNonText() { return gTrue; } - // Does this device require incCharCount to be called for text on - // non-shown layers? + /// Does this device require incCharCount to be called for text on + /// non-shown layers? virtual GBool needCharCount() { return gFalse; } //----- initialization and control - // Set default transform matrix. + /// Set default transform matrix. virtual void setDefaultCTM(double *ctm); - // Check to see if a page slice should be displayed. If this - // returns false, the page display is aborted. Typically, an - // OutputDev will use some alternate means to display the page - // before returning false. + /// Check to see if a page slice should be displayed. If this + /// returns false, the page display is aborted. Typically, an + /// OutputDev will use some alternate means to display the page + /// before returning false. virtual GBool checkPageSlice(Page *page, double hDPI, double vDPI, int rotate, GBool useMediaBox, GBool crop, int sliceX, int sliceY, int sliceW, int sliceH, @@ -131,18 +132,18 @@ public: void *annotDisplayDecideCbkData = NULL) { return gTrue; } - // Start a page. + /// Start a page. virtual void startPage(int pageNum, GfxState *state) {} - // End a page. + /// End a page. virtual void endPage() {} - // Dump page contents to display. + /// Dump page contents to display. virtual void dump() {} //----- coordinate conversion - // Convert between device and user coordinates. + /// Convert between device and user coordinates. virtual void cvtDevToUser(double dx, double dy, double *ux, double *uy); virtual void cvtUserToDev(double ux, double uy, int *dx, int *dy); diff --git a/poppler/PDFDoc.h b/poppler/PDFDoc.h index 468f698..e0f9de4 100644 --- a/poppler/PDFDoc.h +++ b/poppler/PDFDoc.h @@ -65,9 +65,18 @@ enum PDFWriteMode { // PDFDoc //------------------------------------------------------------------------ +/// Appears to be the main class for a pdf document. An object of this class +/// represents a PDF document which is loaded into memory class PDFDoc { public: + /// construct a pdf document by loading a pdf from the file system + /** + * @param fileNameA the path to the document + * @param ownerPassword + * @param userPassword + * @param guiDataA + */ PDFDoc(GooString *fileNameA, GooString *ownerPassword = NULL, GooString *userPassword = NULL, void *guiDataA = NULL); @@ -76,69 +85,111 @@ public: GooString *userPassword = NULL, void *guiDataA = NULL); #endif + /// construct a pdf document by reading in data from a stream + /** + * @param strA the stream to read + * @param ownerPassword + * @param userPassword + * @param guiDataA + */ PDFDoc(BaseStream *strA, GooString *ownerPassword = NULL, GooString *userPassword = NULL, void *guiDataA = NULL); + ~PDFDoc(); static PDFDoc *ErrorPDFDoc(int errorCode, GooString *fileNameA = NULL); - // Was PDF document successfully opened? + /// Was PDF document successfully opened? GBool isOk() { return ok; } - // Get the error code (if isOk() returns false). + /// Get the error code (if isOk() returns false). int getErrorCode() { return errCode; } - // Get the error code returned by fopen() (if getErrorCode() == - // errOpenFile). + /// Get the error code returned by fopen() (if getErrorCode() == + /// errOpenFile). int getFopenErrno() { return fopenErrno; } - // Get file name. + /// Return the filename of the file that was opened to instantiate this + /// pdf document GooString *getFileName() { return fileName; } #ifdef _WIN32 wchar_t *getFileNameU() { return fileNameU; } #endif - // Get the linearization table. + /// Get the linearization table. Linearization *getLinearization(); - // Get the xref table. + /// Get the xref table. XRef *getXRef() { return xref; } - // Get catalog. + /// Get catalog. Catalog *getCatalog() { return catalog; } - // Get optional content configuration + /// Get optional content configuration OCGs *getOptContentConfig() { return catalog->getOptContentConfig(); } - // Get base stream. + /// Get base stream, the stream from which this PDF document was read BaseStream *getBaseStream() { return str; } // Get page parameters. + + /// get the width of a page in the document double getPageMediaWidth(int page) { return getPage(page) ? getPage(page)->getMediaWidth() : 0.0 ; } + + /// get the height of the page in the document + /** + * \todo Doc: What are the units? + */ double getPageMediaHeight(int page) { return getPage(page) ? getPage(page)->getMediaHeight() : 0.0 ; } + + /// get the width of the page after whatever cropping is defined for it + /** + * \todo Doc: the documentation for this is a guess + */ double getPageCropWidth(int page) { return getPage(page) ? getPage(page)->getCropWidth() : 0.0 ; } + + /// get the height of the page after whatever cropping is defined for it + /** + * \todo Doc: the documentation for this is a guess + */ double getPageCropHeight(int page) { return getPage(page) ? getPage(page)->getCropHeight() : 0.0 ; } + + /// get the rotation of a page in the document int getPageRotate(int page) { return getPage(page) ? getPage(page)->getRotate() : 0 ; } - // Get number of pages. + /// Get the number of pages in the document int getNumPages(); - // Return the contents of the metadata stream, or NULL if there is - // no metadata. + /// Return the contents of the metadata stream, or NULL if there is + /// no metadata. GooString *readMetadata() { return catalog->readMetadata(); } - // Return the structure tree root object. + /// Return the structure tree root object. Object *getStructTreeRoot() { return catalog->getStructTreeRoot(); } - // Get page. + /// Return data for the specified page Page *getPage(int page); - // Display a page. + /// Render a page. + /** + * @param out pointer to output device to render to + * @param page the page to render + * @param hDPI horizontal resolution in dots per inch + * @param vDPI vertical resolution in dots per inch + * @param rotate + * @param useMediaBox + * @param crop + * @param printing + * @param abortCheckCbk + * @param abortCheckCbkData + * @param annotDisplayDecideCbk + * @param annotDisplayDecideCbkData + */ void displayPage(OutputDev *out, int page, double hDPI, double vDPI, int rotate, GBool useMediaBox, GBool crop, GBool printing, @@ -147,7 +198,22 @@ public: GBool (*annotDisplayDecideCbk)(Annot *annot, void *user_data) = NULL, void *annotDisplayDecideCbkData = NULL); - // Display a range of pages. + /// Render a range of pages. + /** + * @param out + * @param firstPage + * @param lastPage + * @param hDPI + * @param vDPI + * @param rotate + * @param useMediaBox + * @param crop + * @param printing + * @param abortCheckCbk + * @param abortCheckCbkData + * @param annotDisplayDecideCbk + * @param annotDisplayDecideCbkData + */ void displayPages(OutputDev *out, int firstPage, int lastPage, double hDPI, double vDPI, int rotate, GBool useMediaBox, GBool crop, GBool printing, @@ -156,7 +222,25 @@ public: GBool (*annotDisplayDecideCbk)(Annot *annot, void *user_data) = NULL, void *annotDisplayDecideCbkData = NULL); - // Display part of a page. + /// Render a rectangular subregion of a page. + /** + * @param out + * @param page + * @param hDPI + * @param vDPI + * @param rotate + * @param useMediaBox + * @param crop + * @param printing + * @param sliceX + * @param sliceY + * @param sliceW + * @param sliceH + * @param abortCheckCbk + * @param abortCheckCbkData + * @param annotDisplayDecideCbk + * @param annotDisplayDecideCbkData + */ void displayPageSlice(OutputDev *out, int page, double hDPI, double vDPI, int rotate, GBool useMediaBox, GBool crop, GBool printing, @@ -166,82 +250,131 @@ public: GBool (*annotDisplayDecideCbk)(Annot *annot, void *user_data) = NULL, void *annotDisplayDecideCbkData = NULL); - // Find a page, given its object ID. Returns page number, or 0 if - // not found. + /// Find a page, given its object ID. Returns page number, or 0 if + /// not found. int findPage(int num, int gen) { return catalog->findPage(num, gen); } - // Returns the links for the current page, transferring ownership to - // the caller. + /// Returns the links for the current page, transferring ownership to + /// the caller. Links *getLinks(int page); - // Find a named destination. Returns the link destination, or - // NULL if is not a destination. + /// Find a named destination. Returns the link destination, or + /// NULL if is not a destination. LinkDest *findDest(GooString *name) { return catalog->findDest(name); } - // Process the links for a page. + /// Process the links for a page. void processLinks(OutputDev *out, int page); #ifndef DISABLE_OUTLINE - // Return the outline object. + /// Return the outline object. Outline *getOutline(); #endif - // Is the file encrypted? + /// Is the file encrypted? GBool isEncrypted() { return xref->isEncrypted(); } - // Check various permissions. + /// check for permission to print GBool okToPrint(GBool ignoreOwnerPW = gFalse) { return xref->okToPrint(ignoreOwnerPW); } + + /// check for permission to print at high resolution GBool okToPrintHighRes(GBool ignoreOwnerPW = gFalse) { return xref->okToPrintHighRes(ignoreOwnerPW); } + + /// check for permission to change the document GBool okToChange(GBool ignoreOwnerPW = gFalse) { return xref->okToChange(ignoreOwnerPW); } + + /// check for permission to save a copy of the document GBool okToCopy(GBool ignoreOwnerPW = gFalse) { return xref->okToCopy(ignoreOwnerPW); } + + /// check for permission to add notes to the document GBool okToAddNotes(GBool ignoreOwnerPW = gFalse) { return xref->okToAddNotes(ignoreOwnerPW); } + + /// check for permission to enter data into forms on the document GBool okToFillForm(GBool ignoreOwnerPW = gFalse) { return xref->okToFillForm(ignoreOwnerPW); } + + /// check for permission to run accessibility software on the document + /// (i.e. screen reader) + /** + * @todo Doc: the documentation for this is a guess + * @param ignoreOwnerPW + * @return + */ GBool okToAccessibility(GBool ignoreOwnerPW = gFalse) { return xref->okToAccessibility(ignoreOwnerPW); } + + /// check for permission to assemble document GBool okToAssemble(GBool ignoreOwnerPW = gFalse) { return xref->okToAssemble(ignoreOwnerPW); } - // Is this document linearized? + /// Is this document linearized? + /** + * a linearized PDF is one for which the first page information is moved + * to the beginning of the document so it can be rendered on the web while + * the rest of the document is loading + */ GBool isLinearized(); - // Return the document's Info dictionary (if any). + /// Return the document's Info dictionary (if any). Object *getDocInfo(Object *obj) { return xref->getDocInfo(obj); } Object *getDocInfoNF(Object *obj) { return xref->getDocInfoNF(obj); } - // Return the PDF version specified by the file. + /// Return the PDF version specified by the file . + /** + * The major version is the number before the decimal point, i.e. "1" + * in "1.4" + */ int getPDFMajorVersion() { return pdfMajorVersion; } + + /// Return the PDF version specified by the file. + /** + * The minor version is the number afterthe decimal point, i.e. "4" + * in "1.4" + */ int getPDFMinorVersion() { return pdfMinorVersion; } - //Return the PDF ID in the trailer dictionary (if any). + /// Return the PDF ID in the trailer dictionary (if any). GBool getID(GooString *permanent_id, GooString *update_id); - // Save one page with another name. + /// Save one page with another name. int savePageAs(GooString *name, int pageNo); - // Save this file with another name. + + /// Save this file with another name. int saveAs(GooString *name, PDFWriteMode mode=writeStandard); - // Save this file in the given output stream. + + /// Save this file in the given output stream. int saveAs(OutStream *outStr, PDFWriteMode mode=writeStandard); - // Save this file with another name without saving changes + + /// Save this file with another name without saving changes int saveWithoutChangesAs(GooString *name); - // Save this file in the given output stream without saving changes + + /// Save this file in the given output stream without saving changes int saveWithoutChangesAs(OutStream *outStr); - // Return a pointer to the GUI (XPDFCore or WinPDFCore object). + /// Return a pointer to the GUI (XPDFCore or WinPDFCore object). void *getGUIData() { return guiData; } - // rewrite pageDict with MediaBox, CropBox and new page CTM + /// rewrite pageDict for the specified page with a new MediaBox, CropBox and CTM + /** + * @param pageNo the page number to modify + * @param rotate the new rotation for the page + * @param mediaBox the new mediabox for the page (size of all content) + * @param cropBox the new cropbox for the page (size of cropped content) + * @param pageCTM the new CTM for the page + */ void replacePageDict(int pageNo, int rotate, PDFRectangle *mediaBox, PDFRectangle *cropBox, Object *pageCTM); + + /// @todo Doc: needs documentation void markPageObjects(Dict *pageDict, XRef *xRef, XRef *countRef, Guint numOffset); - // write all objects used by pageDict to outStr + + /// write all objects used by pageDict to outStr Guint writePageObjects(OutStream *outStr, XRef *xRef, Guint numOffset); static Guint writeObject (Object *obj, Ref *ref, OutStream* outStr, XRef *xref, Guint numOffset); static void writeHeader(OutStream *outStr, int major, int minor); @@ -278,6 +411,7 @@ private: // Get hints. Hints *getHints(); + /// Default constructor is private, only construct by loading a document PDFDoc(); void init(); GBool setup(GooString *ownerPassword, GooString *userPassword); @@ -310,10 +444,16 @@ private: #endif Page **pageCache; + /// if the document is loaded and no errors have occured then this will + /// be true GBool ok; + + /// if the status of the document is not ok (i.e. ok false), the + /// error code will be here int errCode; - //If there is an error opening the PDF file with fopen() in the constructor, - //then the POSIX errno will be here. + + /// If there is an error opening the PDF file with fopen() in the constructor, + /// then the POSIX errno will be here. int fopenErrno; Guint startXRefPos; // offset of last xref table diff --git a/poppler/PDFDocBuilder.h b/poppler/PDFDocBuilder.h index d6eccf5..46f5751 100644 --- a/poppler/PDFDocBuilder.h +++ b/poppler/PDFDocBuilder.h @@ -22,6 +22,8 @@ class GooString; // constructing PDFDocs. //------------------------------------------------------------------------ +/// PDFDocBuilder is an abstract class that specifies the interface for +/// constructing PDFDocs. class PDFDocBuilder { public: diff --git a/poppler/Page.h b/poppler/Page.h index 78cedc4..6c96b63 100644 --- a/poppler/Page.h +++ b/poppler/Page.h @@ -49,15 +49,39 @@ class Form; //------------------------------------------------------------------------ +/// Defines a rectangle (for use as an area or region) +/** + * The rectangle is stored as a pair of points + * + * @verbatim + * (x1,y1) ______________ + * | | + * | | + * |______________| + * (x2,y2) + * @endverbatim + * + * @todo Doc: are rectangles (top/left,bottom/right) or (bottom/left,top/right) + */ class PDFRectangle { public: double x1, y1, x2, y2; + /// construct a (0,0) (0,0) rectangle (note, this rectangle is invalid) PDFRectangle() { x1 = y1 = x2 = y2 = 0; } + + /// construct a rectangle from a pair of points PDFRectangle(double x1A, double y1A, double x2A, double y2A) { x1 = x1A; y1 = y1A; x2 = x2A; y2 = y2A; } + + /// returns true the rectangle contains at least one nonzero entry GBool isValid() { return x1 != 0 || y1 != 0 || x2 != 0 || y2 != 0; } + + /// returns true if the query point (x,y) lies inside the rectangle GBool contains(double x, double y) { return x1 <= x && x <= x2 && y1 <= y && y <= y2; } + + /// calculate the intersection of this rectangle with another rectangle, and + /// store the result in this rectangle void clipTo(PDFRectangle *rect); }; @@ -65,6 +89,9 @@ public: // PageAttrs //------------------------------------------------------------------------ + +/// Stores attributes for a page including it's varius boxes and other +/// information class PageAttrs { public: @@ -77,20 +104,85 @@ public: ~PageAttrs(); // Accessors. + + /// return the media box defined for a page + /** + * The media box is at least as large as all other boxes, and essentially + * defines the largest page boarder + * + * @see http://www.prepressure.com/pdf/basics/page_boxes + */ PDFRectangle *getMediaBox() { return &mediaBox; } + + /// return the crop box defined for a page + /** + * The crop box is the region to which the contents of the page should + * be clipped. This is the effective size of the page that is displayed + * by acrobat reader and during printing + * + * @see http://www.prepressure.com/pdf/basics/page_boxes + */ PDFRectangle *getCropBox() { return &cropBox; } + + /// returns true if the page has a crop box GBool isCropped() { return haveCropBox; } + + /// return the bleed box for the page + /** + * The bleed box is the size to which page contents should be clipped + * within a production environment. It is generally a few mm larger than + * the trim box (which is the intended size of the production document). + * I think the reason this is bigger is that you generally need to leave + * a margin for a physical printing device because it can't really drop + * ink on the very edge of the paper. Evidently, the bleed box is + * very often the same as the crop box. + * + * @see http://www.prepressure.com/pdf/basics/page_boxes + */ PDFRectangle *getBleedBox() { return &bleedBox; } + + /// return the trim box + /** + * The trim box defines the intended region of the finished page. + * Evidently it is used by a lot of production software as this is the + * region of the final product to be printed, and so if several + * documents are being layed out on the same sheet, this is the + * only size that matters for a given document. + * + * @see http://www.prepressure.com/pdf/basics/page_boxes + */ PDFRectangle *getTrimBox() { return &trimBox; } + + /// return the art box + /** + * The art box defines a region of the page which is of particular + * importance. Evidently it is rarely used in applications. + * + * @see http://www.prepressure.com/pdf/basics/page_boxes + */ PDFRectangle *getArtBox() { return &artBox; } + + /// return the rotation of the page + /** + * @todo Doc: figure out units (degrees?, enum?) + */ int getRotate() { return rotate; } + + /// return the last modified string of the page + /** + * @todo Doc: is this a date-string or a user or what? + */ GooString *getLastModified() { return lastModified.isString() ? lastModified.getString() : (GooString *)NULL; } + + Dict *getBoxColorInfo() { return boxColorInfo.isDict() ? boxColorInfo.getDict() : (Dict *)NULL; } Dict *getGroup() { return group.isDict() ? group.getDict() : (Dict *)NULL; } + + /// return meta data stream for this page Stream *getMetadata() { return metadata.isStream() ? metadata.getStream() : (Stream *)NULL; } Dict *getPieceInfo() @@ -101,7 +193,8 @@ public: Dict *getResourceDict() { return resources.isDict() ? resources.getDict() : (Dict *)NULL; } - // Clip all other boxes to the MediaBox. + + /// Clip all other boxes to the MediaBox. void clipBoxes(); private: @@ -128,6 +221,9 @@ private: // Page //------------------------------------------------------------------------ + +/// Object representing a single page from a PDF document, including it's +/// contents and all meta data class Page { public: @@ -141,66 +237,153 @@ public: GBool isOk() { return ok; } // Get page parameters. + /// return the page number of this page within it's document int getNum() { return num; } + + /// return the media box for the page + /** + * see PageAttrs::getMediaBox + */ PDFRectangle *getMediaBox() { return attrs->getMediaBox(); } + + /// return the crop box for this page + /** + * see PageAttrs::getCropBox + */ PDFRectangle *getCropBox() { return attrs->getCropBox(); } + + /// return true if this page has a crop box GBool isCropped() { return attrs->isCropped(); } + + /// return the width of the media box + /** + * @see PageAttrs::getMediaBox + */ double getMediaWidth() { return attrs->getMediaBox()->x2 - attrs->getMediaBox()->x1; } + + /// return the height of the media box + /** + * @see PageAttrs::getMediaBox + */ double getMediaHeight() { return attrs->getMediaBox()->y2 - attrs->getMediaBox()->y1; } + + /// return the width of the crop box + /** + * @see PageAttrs::getCropBox + */ double getCropWidth() { return attrs->getCropBox()->x2 - attrs->getCropBox()->x1; } + + /// return the height of the crop box + /** + * @see PageAttrs::getCropBox + */ double getCropHeight() { return attrs->getCropBox()->y2 - attrs->getCropBox()->y1; } + + /// return the bleed box for the page + /** + * @see PageAttrs::getBleedBox + */ PDFRectangle *getBleedBox() { return attrs->getBleedBox(); } + + /// return the trim box for the page + /** + * @see PageAttrs::getTrimBox + */ PDFRectangle *getTrimBox() { return attrs->getTrimBox(); } + + /// return the art box for the page + /** + * @see PageAttrs::getArtBox + */ PDFRectangle *getArtBox() { return attrs->getArtBox(); } + + /// get the rotation for the page + /** + * @see PageAttrs::getRotate + */ int getRotate() { return attrs->getRotate(); } + + /// get the last modified info for the page + /** + * @see PageAttrs::getLastModified + */ GooString *getLastModified() { return attrs->getLastModified(); } + + /// get the box color info for the page + /** + * @see PageAttrs::getBoxColorInfo + */ Dict *getBoxColorInfo() { return attrs->getBoxColorInfo(); } + + /// get the group for the page + /** + * @see PageAttrs::getGroup + */ Dict *getGroup() { return attrs->getGroup(); } + + /// get the meta data stream for the page + /** + * @see PageAttrs::getMetadata + */ Stream *getMetadata() { return attrs->getMetadata(); } + Dict *getPieceInfo() { return attrs->getPieceInfo(); } Dict *getSeparationInfo() { return attrs->getSeparationInfo(); } PDFDoc *getDoc() { return doc; } Ref getRef() { return pageRef; } - // Get resource dictionary. + /// Get resource dictionary. Dict *getResourceDict() { return attrs->getResourceDict(); } - // Get annotations array. + /// Get annotations array. Object *getAnnots(Object *obj) { return annotsObj.fetch(xref, obj); } - // Add a new annotation to the page + + /// Add a new annotation to the page void addAnnot(Annot *annot); - // Remove an existing annotation from the page + + /// Remove an existing annotation from the page void removeAnnot(Annot *annot); - // Return a list of links. + /// Return a list of links. Links *getLinks(); - // Return a list of annots. It will be valid until the page is destroyed + /// Return a list of annots. It will be valid until the page is destroyed Annots *getAnnots(); - // Get contents. + /// Get contents. Object *getContents(Object *obj) { return contents.fetch(xref, obj); } - // Get thumb. + /// Get thumb. Object *getThumb(Object *obj) { return thumb.fetch(xref, obj); } + + /// load thumbnail image into the buffer at \p data + /** + * @param[out] data the thumbnail image data + * @param[out] width the width of the thumbnail image + * @param[out] height the height of the thumbnail image + * @param[out] rowstride number of bytes in each row of the data (including + * padding) + * + * @return true on success, false on failure + */ GBool loadThumb(unsigned char **data, int *width, int *height, int *rowstride); - // Get transition. + /// Get transition. Object *getTrans(Object *obj) { return trans.fetch(xref, obj); } - // Get form. + /// Get form. FormPageWidgets *getFormWidgets(); - // Get duration, the maximum length of time, in seconds, - // that the page is displayed before the presentation automatically - // advances to the next page + /// Get duration, the maximum length of time, in seconds, + /// that the page is displayed before the presentation automatically + /// advances to the next page double getDuration() { return duration; } - // Get actions + /// Get actions Object *getActions(Object *obj) { return actions.fetch(xref, obj); } Gfx *createGfx(OutputDev *out, double hDPI, double vDPI, @@ -210,7 +393,7 @@ public: GBool (*abortCheckCbk)(void *data), void *abortCheckCbkData); - // Display a page. + /// Display a page. void display(OutputDev *out, double hDPI, double vDPI, int rotate, GBool useMediaBox, GBool crop, GBool printing, @@ -219,7 +402,7 @@ public: GBool (*annotDisplayDecideCbk)(Annot *annot, void *user_data) = NULL, void *annotDisplayDecideCbkData = NULL); - // Display part of a page. + /// Display part of a page. void displaySlice(OutputDev *out, double hDPI, double vDPI, int rotate, GBool useMediaBox, GBool crop, int sliceX, int sliceY, int sliceW, int sliceH, @@ -238,26 +421,29 @@ public: void processLinks(OutputDev *out); - // Get the page's default CTM. + /// Get the page's default CTM. + /** + * @todo Doc: is CTM "Current Transformation Matrix? + */ void getDefaultCTM(double *ctm, double hDPI, double vDPI, int rotate, GBool useMediaBox, GBool upsideDown); private: PDFDoc *doc; - XRef *xref; // the xref table for this PDF file - Object pageObj; // page dictionary - Ref pageRef; // page reference - int num; // page number - PageAttrs *attrs; // page attributes - Annots *annots; // annotations - Object annotsObj; // annotations array - Object contents; // page contents - Object thumb; // page thumbnail - Object trans; // page transition - Object actions; // page addiction actions - double duration; // page duration - GBool ok; // true if page is valid + XRef *xref; ///< the xref table for this PDF file + Object pageObj; ///< page dictionary + Ref pageRef; ///< page reference + int num; ///< page number + PageAttrs *attrs; ///< page attributes + Annots *annots; ///< annotations + Object annotsObj; ///< annotations array + Object contents; ///< page contents + Object thumb; ///< page thumbnail + Object trans; ///< page transition + Object actions; ///< page addiction actions + double duration; ///< page duration + GBool ok; ///< true if page is valid }; #endif diff --git a/poppler/XRef.h b/poppler/XRef.h index 148a5ce..2f2182e 100644 --- a/poppler/XRef.h +++ b/poppler/XRef.h @@ -63,35 +63,46 @@ struct XRefEntry { Object obj; //if this entry was updated, obj will contains the updated object }; + +/// An XRef is an item in the PDF Cross Reference Table +/** + * The xref is the index by which all of the indirect objects, in the PDF + * file, are located. A single PDF file can contain multiple xref tables + * if the file has been incrementally saved or linearized. + * + * @see http://labs.appligent.com/pdfblog/pdf_cross_reference_table.php + */ class XRef { public: - // Constructor, create an empty XRef, used for PDF writing + /// Constructor, create an empty XRef, used for PDF writing XRef(); - // Constructor, create an empty XRef but with info dict, used for PDF writing + + /// Constructor, create an empty XRef but with info dict, used for PDF writing XRef(Object *trailerDictA); - // Constructor. Read xref table from stream. + + /// Constructor. Read xref table from stream. XRef(BaseStream *strA, Guint pos, Guint mainXRefEntriesOffsetA = 0, GBool *wasReconstructed = NULL, GBool reconstruct = false); - // Destructor. + /// Destructor. ~XRef(); - // Is xref table valid? + /// Is xref table valid? GBool isOk() { return ok; } - // Is the last XRef section a stream or a table? + /// Is the last XRef section a stream or a table? GBool isXRefStream() { return xRefStream; } - // Get the error code (if isOk() returns false). + /// Get the error code (if isOk() returns false). int getErrorCode() { return errCode; } - // Set the encryption parameters. + /// Set the encryption parameters. void setEncryption(int permFlagsA, GBool ownerPasswordOkA, Guchar *fileKeyA, int keyLengthA, int encVersionA, int encRevisionA, CryptAlgorithm encAlgorithmA); - // Is the file encrypted? + /// Is the file encrypted? GBool isEncrypted() { return encrypted; } // Check various permissions. @@ -105,28 +116,32 @@ public: GBool okToAssemble(GBool ignoreOwnerPW = gFalse); int getPermFlags() { return permFlags; } - // Get catalog object. + /// Get catalog object. Object *getCatalog(Object *obj) { return fetch(rootNum, rootGen, obj); } - // Fetch an indirect reference. + /// Fetch an indirect reference. Object *fetch(int num, int gen, Object *obj, int recursion = 0); // Return the document's Info dictionary (if any). Object *getDocInfo(Object *obj); Object *getDocInfoNF(Object *obj); - // Return the number of objects in the xref table. + /// Return the number of objects in the xref table. int getNumObjects() { return size; } // Return the catalog object reference. int getRootNum() { return rootNum; } int getRootGen() { return rootGen; } - // Get end position for a stream in a damaged file. - // Returns false if unknown or file is not damaged. + /// Get end position for a stream in a damaged file. + /** + * @param streamStart + * @param streamEnd + * @return false if unknown or file is not damaged. + */ GBool getStreamEnd(Guint streamStart, Guint *streamEnd); - // Retuns the entry that belongs to the offset + /// Returns the entry that belongs to the offset int getNumEntry(Guint offset); // Direct access. @@ -139,9 +154,10 @@ public: void removeIndirectObject(Ref r); void add(int num, int gen, Guint offs, GBool used); - // Output XRef table to stream + /// Output XRef table to stream void writeTableToFile(OutStream* outStr, GBool writeAllEntries); - // Output XRef stream contents to GooString and fill trailerDict fields accordingly + + /// Output XRef stream contents to GooString and fill trailerDict fields accordingly void writeStreamToBuffer(GooString *stmBuf, Dict *xrefDict, XRef *xref); private: -- 1.7.5.4 From 472b86627e198128cb7f2622dd6acf14db36b29b Mon Sep 17 00:00:00 2001 From: Josh Bialkowski Date: Tue, 10 Jul 2012 16:34:12 -0400 Subject: [PATCH 2/2] fixed tab issues --- poppler/Link.h | 18 +++++++++--------- poppler/Page.h | 18 +++++++++--------- 2 files changed, 18 insertions(+), 18 deletions(-) diff --git a/poppler/Link.h b/poppler/Link.h index 64476ed..295d5b4 100644 --- a/poppler/Link.h +++ b/poppler/Link.h @@ -46,17 +46,17 @@ class Annots; /// Enumerates the types of a PDF hyper-reference (link) enum LinkActionKind { - actionGoTo, ///< go to destination - actionGoToR, ///< go to destination in new file - actionLaunch, ///< launch app (or open document) - actionURI, ///< URI - actionNamed, ///< named action - actionMovie, ///< movie action + actionGoTo, ///< go to destination + actionGoToR, ///< go to destination in new file + actionLaunch, ///< launch app (or open document) + actionURI, ///< URI + actionNamed, ///< named action + actionMovie, ///< movie action actionRendition, - actionSound, ///< sound action - actionJavaScript, ///< JavaScript action + actionSound, ///< sound action + actionJavaScript, ///< JavaScript action actionOCGState, ///< Set-OCG-State action - actionUnknown ///< anything else + actionUnknown ///< anything else }; class LinkAction { diff --git a/poppler/Page.h b/poppler/Page.h index 6c96b63..993f76c 100644 --- a/poppler/Page.h +++ b/poppler/Page.h @@ -431,19 +431,19 @@ public: private: PDFDoc *doc; - XRef *xref; ///< the xref table for this PDF file + XRef *xref; ///< the xref table for this PDF file Object pageObj; ///< page dictionary Ref pageRef; ///< page reference - int num; ///< page number - PageAttrs *attrs; ///< page attributes + int num; ///< page number + PageAttrs *attrs; ///< page attributes Annots *annots; ///< annotations - Object annotsObj; ///< annotations array - Object contents; ///< page contents - Object thumb; ///< page thumbnail - Object trans; ///< page transition - Object actions; ///< page addiction actions + Object annotsObj; ///< annotations array + Object contents; ///< page contents + Object thumb; ///< page thumbnail + Object trans; ///< page transition + Object actions; ///< page addiction actions double duration; ///< page duration - GBool ok; ///< true if page is valid + GBool ok; ///< true if page is valid }; #endif -- 1.7.5.4