As I've been trying to learn the API I've been adding doxygen style comments my own git branch. I'm not sure if all my comments are correct but it has helped me keep track of what I've figured out thus far, and perhaps may be useful to others.
I've attached a patch of my changes. I believe I've only touched comment lines, except for one or two class member lists which were commented (I added ///< so that doxygen picks up those comments too). I haven't documented a lot, just some comments here and there on some of the main components (I think). Feel free to use or throw away, as you please. I will likely continue to add comments until I get more comfortable with the library, so if such contributions appear to be useful, let me know and I will continue to submit my documentation. -Josh
>From 9d480eefad9a4ee8f243f473dc369097340904bb Mon Sep 17 00:00:00 2001 From: Josh Bialkowski <[email protected]> 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 <[email protected]> // Copyright (C) 2009, 2011 Carlos Garcia Campos <[email protected]> // Copyright (C) 2009, 2012 Albert Astals Cid <[email protected]> -// Copyright (C) 2010 Christian Feuers�nger <[email protected]> +// Copyright (C) 2010 Christian Feuers�nger <[email protected]> // Copyright (C) 2012 Fabio D'Urso <[email protected]> // // 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 <name> is not a destination. + /// Find a named destination. Returns the link destination, or + /// NULL if <name> 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 <[email protected]> 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
_______________________________________________ poppler mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/poppler
