Commit da8e6d4c authored by Albert Astals Cid's avatar Albert Astals Cid
Browse files

really commit pino's patch :-S

parent 4f26e650
......@@ -17,13 +17,13 @@
# The PROJECT_NAME tag is a single word (or a sequence of words surrounded
# by quotes) that should identify the project.
PROJECT_NAME =
PROJECT_NAME = "Poppler Qt4"
# The PROJECT_NUMBER tag can be used to enter a project or revision number.
# This could be handy for archiving the generated documentation or
# if some version control system is used.
PROJECT_NUMBER =
PROJECT_NUMBER = 0.5.80
# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
# base path where the generated documentation will be put.
......@@ -444,7 +444,12 @@ WARN_LOGFILE =
# directories like "/usr/src/myproject". Separate the files or directories
# with spaces.
INPUT = . ../../qt/poppler-page-transition.h
INPUT = \
Mainpage.dox \
poppler-annotation.h \
poppler-link.h \
poppler-qt4.h \
../../qt/poppler-page-transition.h
# If the value of the INPUT tag contains directories, you can use the
# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
......
......@@ -37,53 +37,51 @@ simply need to add the following two lines to their C++ source files:
#include <poppler-qt4.h>
@endcode
The \#define statement is required at the moment. You indicate that you
The \c \#define statement is required at the moment. You indicate that you
think you know what you are doing, and understand that the API is
subject to change.
A PDF document can then be loaded as follows.
A PDF document can then be loaded as follows:
@code
QString filename;
Poppler::Document* document = Poppler::Document::load(filename.ascii());
if (!document || document->isLocked()) {
... error message ....
// ... error message ....
delete document;
return;
}
@endcode
Pages can be rendered to QPixmaps with the following commands.
Pages can be rendered to QImages with the following commands:
@code
// Paranoid safety check
if (document == 0) {
... error message ...
// ... error message ...
return;
}
// Access page of the PDF file
Poppler::Page* pdfPage = document->page(pageNumber); // Document starts at page 0
if (pdfPage == 0) {
... error message ...
// ... error message ...
return;
}
// Generate a QPixmap of the rendered page
QPixmap* pixmap = pdfPage->splashRenderToPixmap(0, 0, 0, 0, xres, yres );
if (pixmap == 0) {
... error message ...
// Generate a QImage of the rendered page
QImage image = pdfPage->renderToImage(xres, yres, x, y, width, height);
if (image.isNull()) {
// ... error message ...
return;
}
... use pixmap ...
delete pixmap;
// ... use image ...
@endcode
Finally, don't forget to destroy the document.
Finally, don't forget to destroy the document:
@code
delete document;
......
......@@ -33,24 +33,31 @@ class Annotation;
class Link;
/**
* @short Helper class for (recoursive) annotation retrieval/storage.
* \short Helper class for (recursive) Annotation retrieval/storage.
*
*/
class AnnotationUtils
{
public:
// restore an annotation (with revisions if needed) from a dom
// element. returns a pointer to the complete annotation or 0 if
// element is invalid.
/**
* Restore an Annotation (with revisions if needed) from the DOM
* element \p annElement.
* \returns a pointer to the complete Annotation or 0 if element is
* invalid.
*/
static Annotation * createAnnotation( const QDomElement & annElement );
// save the 'ann' annotations as a child of parentElement taking
// care of saving all revisions if 'ann' has any.
/**
* Save the Annotation \p ann as a child of \p annElement taking
* care of saving all revisions if \p ann has any.
*/
static void storeAnnotation( const Annotation * ann,
QDomElement & annElement, QDomDocument & document );
// return an element called 'name' from the direct children of
// parentNode or a null element if not found
/**
* Returns an element called \p name from the direct children of
* \p parentNode or a null element if not found.
*/
static QDomElement findChildElement( const QDomNode & parentNode,
const QString & name );
......@@ -60,7 +67,7 @@ class AnnotationUtils
/**
* @short Annotation struct holds properties shared by all annotations.
* \short Annotation struct holds properties shared by all annotations.
*
* An Annotation is an object (text note, highlight, sound, popup window, ..)
* contained by a Page in the document.
......@@ -80,14 +87,14 @@ struct Annotation
enum RevType { None = 1, Marked = 2, Unmarked = 4, Accepted = 8, Rejected = 16, Cancelled = 32, Completed = 64 };
/** properties: contents related */
/* properties: contents related */
QString author; // ''
QString contents; // ''
QString uniqueName; // '#NUMBER#'
QDateTime modifyDate; // before or equal to currentDateTime()
QDateTime creationDate; // before or equal to modifyDate
/** properties: look/interaction related */
/* properties: look/interaction related */
int flags; // 0
QRectF boundary; // valid or isNull()
struct Style
......@@ -109,7 +116,7 @@ struct Annotation
Style();
} style;
/** properties: popup window */
/* properties: popup window */
struct Window
{
// window state (Hidden, FixedRotation, Deny* flags allowed)
......@@ -126,7 +133,7 @@ struct Annotation
Window();
} window;
/** properties: versioning */
/* properties: versioning */
struct Revision
{
// child revision
......
......@@ -72,10 +72,10 @@ class LinkDestination
};
/**
* @short Encapsulates data that describes a link.
* \short Encapsulates data that describes a link.
*
* This is the base class for links. It makes mandatory for inherited
* widgets to reimplement the 'linkType' method and return the type of
* kind of links to reimplement the linkType() method and return the type of
* the link described by the reimplemented class.
*/
class Link
......@@ -83,13 +83,37 @@ class Link
public:
Link( const QRectF &linkArea );
// get link type (inherited classes mustreturn an unique identifier)
enum LinkType { None, Goto, Execute, Browse, Action, Sound, Movie };
/**
* The possible kinds of link.
*
* \internal
* Inherited classes must return an unique identifier
*/
enum LinkType
{
None, ///< Unknown link
Goto, ///< A "Go To" link
Execute,
Browse,
Action,
Sound, ///< A link representing a sound to be played
Movie
};
/**
* The type of this link.
*/
virtual LinkType linkType() const;
// virtual destructor
virtual ~Link();
/**
* The area of a Page where the link should be active.
*
* \note this can be a null rect, in this case the link represents
* a general action
*/
QRectF linkArea() const;
private:
......@@ -102,9 +126,13 @@ class LinkGoto : public Link
{
public:
LinkGoto( const QRectF &linkArea, QString extFileName, const LinkDestination & destination );
// query for goto parameters
/**
* Whether the destination is in an external document
* (i.e. not the current document)
*/
bool isExternal() const;
// query for goto parameters
const QString & fileName() const;
const LinkDestination & destination() const;
LinkType linkType() const;
......@@ -118,7 +146,9 @@ class LinkGoto : public Link
class LinkExecute : public Link
{
public:
// query for filename / parameters
/**
* The file name to be executed
*/
const QString & fileName() const;
const QString & parameters() const;
......@@ -131,7 +161,7 @@ class LinkExecute : public Link
QString m_parameters;
};
/** Browse: an URL to open, ranging from 'http://' to 'mailto:' etc.. **/
/** Browse: an URL to open, ranging from 'http://' to 'mailto:', etc. **/
class LinkBrowse : public Link
{
public:
......@@ -150,7 +180,9 @@ class LinkBrowse : public Link
class LinkAction : public Link
{
public:
// define types of actions
/**
* The possible types of actions
*/
enum ActionType { PageFirst = 1,
PagePrev = 2,
PageNext = 3,
......@@ -164,7 +196,9 @@ class LinkAction : public Link
GoToPage = 11,
Close = 12 };
// query for action type
/**
* The action of the current LinkAction
*/
ActionType actionType() const;
// create a Link_Action
......@@ -184,10 +218,24 @@ class LinkSound : public Link
LinkType linkType() const;
/**
* The volume to be used when playing the sound.
*
* The volume is in the range [ -1, 1 ], where:
* - a negative number: no volume (mute)
* - 1: full volume
*/
double volume() const;
bool synchronous() const;
/**
* Whether the sound should be played continuously (that is,
* started again when it ends)
*/
bool repeat() const;
bool mix() const;
/**
* The sound object to be played
*/
SoundObject *sound() const;
private:
......
......@@ -47,7 +47,7 @@ namespace Poppler {
class TextBoxData;
/**
describes the physical location of text on a document page
Describes the physical location of text on a document page
This very simple class describes the physical location of text
on the page. It consists of
......@@ -59,19 +59,19 @@ namespace Poppler {
friend class Page;
public:
/**
The default constructor sets the text and the rectangle the
contains the text. Coordinated for the bBox are in points =
The default constructor sets the \p text and the rectangle that
contains the text. Coordinated for the \p bBox are in points =
1/72 of an inch.
*/
TextBox(const QString& text, const QRectF &bBox);
/**
returns the text
Returns the text of this text box
*/
const QString &text() const;
/**
returns the position of the text, in point, i.e., 1/72 of
Returns the position of the text, in point, i.e., 1/72 of
an inch
*/
const QRectF &boundingBox() const;
......@@ -87,11 +87,11 @@ namespace Poppler {
};
class FontInfoData;
/**
Container class for information about a font within a PDF
document
*/
class FontInfoData;
class FontInfo {
public:
enum Type {
......@@ -120,7 +120,8 @@ namespace Poppler {
const QString &name() const;
/**
The path of the font file used to represent this font on this system.
The path of the font file used to represent this font on this system,
or a null string is the font is embedded
*/
const QString &file() const;
......@@ -163,13 +164,15 @@ namespace Poppler {
};
class EmbeddedFileData;
/**
Container class for an embedded file with a PDF document
*/
class EmbeddedFileData;
class EmbeddedFile {
public:
/**
\internal
Create a new embedded file container
*/
EmbeddedFile(EmbFile *embfile);
......@@ -201,7 +204,7 @@ namespace Poppler {
QDateTime createDate() const;
/**
The data as an array
The data as a byte array
*/
QByteArray data();
......@@ -234,14 +237,15 @@ namespace Poppler {
};
/**
Render the page to a QImage using the specified renderer
Render the page to a QImage using the current Document renderer
(see Document::renderBackend())
If x=y=w=h=-1, the method will automatically compute the
size of the pixmap from the horizontal and vertical
resolutions specified in xres and yres. Otherwise, the
If \p x = \p y = \p w = \p h = -1, the method will automatically
compute the size of the image from the horizontal and vertical
resolutions specified in \p xres and \p yres. Otherwise, the
method renders only a part of the page, specified by the
parameters (x, y, w, h) in pixel coordinates. The returned
QImage then has size (w, h), independent of the page
parameters (\p x, \p y, \p w, \p h) in pixel coordinates. The returned
QImage then has size (\p w, \p h), independent of the page
size.
\param x specifies the left x-coordinate of the box, in
......@@ -264,7 +268,7 @@ namespace Poppler {
\param rotate how to rotate the page
\warning The parameter (x,y,w,h) are not
\warning The parameter (\p x, \p y, \p w, \p h) are not
well-tested. Unusual or meaningless parameters may lead to
rather unexpected results.
......@@ -318,14 +322,14 @@ namespace Poppler {
QSizeF pageSizeF() const;
/**
The dimensions of the page, in pixels.
The size of the page, in pixels
*/
QSize pageSize() const;
/**
\brief Returns the transition of this page
Returns the transition of this page
@returns a pointer to a PageTransition structure that
\returns a pointer to a PageTransition structure that
defines how transition to this page shall be performed. The
PageTransition structure is owned by this page, and will
automatically be destroyed when this page class is
......@@ -359,7 +363,8 @@ namespace Poppler {
void defaultCTM(double *CTM, double dpiX, double dpiY, int rotate, bool upsideDown);
/**
Gets the links of the page once it has been rendered if doLinks was true
Gets the links of the page once it has been rendered with renderToImage()
if \c doLinks was true
*/
QList<Link*> links() const;
......@@ -430,7 +435,7 @@ namespace Poppler {
const QByteArray &userPassword=QByteArray());
/**
Get a specified page
Get a specified Page
Note that this follows the PDF standard of being zero based - if you
want the first page, then you need an index of zero.
......@@ -442,6 +447,7 @@ namespace Poppler {
/**
\overload
The intent is that you can pass in a label like "ix" and
get the page with that label (which might be in the table of
contents), or pass in "1" and get the page that the user
......@@ -486,11 +492,15 @@ namespace Poppler {
You would use this method with something like:
\code
QDateTime created = m_doc->date("CreationDate");
QDateTime modded = m_doc->date("ModDate");
QDateTime created = m_doc->date("CreationDate");
QDateTime modified = m_doc->date("ModDate");
\endcode
\param data the type of date that is required (such as CreationDate or ModDate)
The available dates are:
- CreationDate: the date of creation of the document
- ModDate: the date of the last change in the document
\param data the type of date that is required
*/
QDateTime date( const QString & data ) const;
......@@ -500,12 +510,12 @@ namespace Poppler {
You would use this method with something like:
\code
QString title = m_doc->info("Title");
QString subject = m_doc->info("Subject");
QString title = m_doc->info("Title");
QString subject = m_doc->info("Subject");
\endcode
In addition to Title and Subject, other information that may be available
includes Author, Keywords, Creator and Producer.
In addition to \c Title and \c Subject, other information that may
be available include \c Author, \c Keywords, \c Creator and \c Producer.
\param data the information that is required
......@@ -591,8 +601,9 @@ namespace Poppler {
/**
Test if the permissions on the document allow it to be
"assembled" - insertion, rotation and deletion of pages;
or creation of bookmarks and thumbnail images. This can
be true even if okToChange is false.
or creation of bookmarks and thumbnail images.
\note this can be true even if okToChange() is false
*/
bool okToAssemble() const;
......@@ -614,6 +625,7 @@ namespace Poppler {
/**
\overload
\param numPages the number of pages to scan
\param fontList pointer to the list where the font information
should be placed
......@@ -654,27 +666,43 @@ namespace Poppler {
LinkDestination *linkDestination( const QString &name );
/**
If you are using QPrinter you can get paper size by doing
QPrinter dummy(QPrinter::PrinterResolution);
dummy.setFullPage(true);
dummy.setPageSize(myPageSize);
width = dummy.width();
height = dummy.height();
Prints the document to the PostScript file \p fileName
If you are using QPrinter you can get paper size by doing:
\code
QPrinter dummy(QPrinter::PrinterResolution);
dummy.setFullPage(true);
dummy.setPageSize(myPageSize);
width = dummy.width();
height = dummy.height();
\endcode
*/
bool print(const QString &fileName, const QList<int> pageList, double hDPI, double vDPI, int rotate, int paperWidth, int paperHeight);
/**
Sets the paper color, if not set it is white by default.
Sets the paper color
\param color the new paper color
*/
void setPaperColor(const QColor &color);
/**
The paper color
The default color is white.
*/
QColor paperColor() const;
/**
Sets the backend used to render the pages.
The default backend is @ref SplashBackend
\param backend the new rendering backend
*/
void setRenderBackend( RenderBackend backend );
/**
The currently set render backend
The default backend is \ref SplashBackend
*/
RenderBackend renderBackend() const;
~Document();
......@@ -711,12 +739,15 @@ namespace Poppler {
The encoding format used for the sound
*/
enum SoundEncoding {
Raw, ///< Raw encoding, with unspecified or unsigned values in the range [ 0, 2^B 1 ]
Raw, ///< Raw encoding, with unspecified or unsigned values in the range [ 0, 2^B - 1 ]
Signed, ///< Twos-complement values
muLaw, ///< mu-law-encoded samples
ALaw ///< A-law-encoded samples
};
/**
\internal
*/
SoundObject(Sound *popplersound);
SoundObject(const SoundObject &s);
......@@ -724,17 +755,17 @@ namespace Poppler {
~SoundObject();
/**
Is the sound embedded (@ref Embedded ) or external (@ref External )?
Is the sound embedded (\ref Embedded ) or external (\ref External )?
*/
SoundType soundType() const;
/**
The URL of the sound file to be played, in case of @ref External
The URL of the sound file to be played, in case of \ref External
*/
QString url() const;
/**
The data of the sound, in case of @ref Embedded
The data of the sound, in case of \ref Embedded
*/
QByteArray data() const;
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment