[poppler] 3 commits - qt4/src
Pino Toscano
pino at kemper.freedesktop.org
Sun Sep 28 14:42:10 PDT 2008
qt4/src/Mainpage.dox | 10 ---
qt4/src/poppler-link.h | 92 +++++++++++++++++++++++++++--
qt4/src/poppler-ps-converter.cc | 2
qt4/src/poppler-qt4.h | 123 +++++++++++++++++++++++++++-------------
4 files changed, 171 insertions(+), 56 deletions(-)
New commits:
commit a29984ab777c64a1cb286b667a6a91ad9b191f40
Merge: f399afe... 6865872...
Author: Pino Toscano <pino at kde.org>
Date: Sun Sep 28 23:39:08 2008 +0200
Merge branch 'master' of ssh://pino@git.freedesktop.org/git/poppler/poppler
commit f399afe6f6b9c250327d0e4c5b3f2839889d7095
Author: Pino Toscano <pino at kde.org>
Date: Sun Sep 28 23:38:34 2008 +0200
[Qt4] various apidox improvements
diff --git a/qt4/src/Mainpage.dox b/qt4/src/Mainpage.dox
index 94e74db..f5dc6ef 100644
--- a/qt4/src/Mainpage.dox
+++ b/qt4/src/Mainpage.dox
@@ -12,18 +12,12 @@ internals.
The %Poppler Qt4 interface library is quite stable and working.
-It offers a dynamic way to change the render backend (see
-\ref Poppler::Document::setRenderBackend() "setRenderBackend()"). Currently
-there two backends offered by the library, but only the Splash engine works
-well and has been tested.
-
-
@section refimpl Example Programs
Examples programs can be found in the qt4/test directory. The %Poppler
Qt4 interface library is also used in the development version of KDE's
-document viewer <a href="http://okular.kde.org">okular</a>. The source files
-for okular's PDF plugin (%Poppler-based) can be found on the subversion server
+document viewer <a href="http://okular.kde.org">Okular</a>. The source files
+for Okular's PDF plugin (%Poppler-based) can be found on the subversion server
of the KDE project, under
<a
href="http://websvn.kde.org/trunk/KDE/kdegraphics/okular/generators/poppler">this
diff --git a/qt4/src/poppler-link.h b/qt4/src/poppler-link.h
index 7a8492a..bca464c 100644
--- a/qt4/src/poppler-link.h
+++ b/qt4/src/poppler-link.h
@@ -42,15 +42,28 @@ class LinkDestinationPrivate;
class SoundObject;
/**
- * \short Encapsulates data that describes a link destination.
+ * \short A destination.
+ *
+ * The LinkDestination class represent a "destination" (in terms of visual
+ * viewport to be displayed) for \link Poppler::LinkGoto GoTo\endlink links,
+ * and items in the table of contents (TOC) of a document.
*
* Coordinates are in 0..1 range
*/
class POPPLER_QT4_EXPORT LinkDestination
{
public:
+ /**
+ * The possible kind of "viewport destination".
+ */
enum Kind
{
+ /**
+ * The new viewport is specified in terms of:
+ * - possibile new left coordinate (see isChangeLeft() )
+ * - possibile new top coordinate (see isChangeTop() )
+ * - possibile new zoom level (see isChangeZoom() )
+ */
destXYZ = 1,
destFit = 2,
destFitH = 3,
@@ -79,14 +92,45 @@ class POPPLER_QT4_EXPORT LinkDestination
* The kind of destination.
*/
Kind kind() const;
+ /**
+ * Which page is the target of this destination.
+ *
+ * \note this number is 1-based, so for a 5 pages document the
+ * valid page numbers go from 1 to 5 (both included).
+ */
int pageNumber() const;
+ /**
+ * The new left for the viewport of the target page, in case
+ * it is specified to be changed (see isChangeLeft() )
+ */
double left() const;
double bottom() const;
double right() const;
+ /**
+ * The new top for the viewport of the target page, in case
+ * it is specified to be changed (see isChangeTop() )
+ */
double top() const;
double zoom() const;
+ /**
+ * Whether the left of the viewport on the target page should
+ * be changed.
+ *
+ * \see left()
+ */
bool isChangeLeft() const;
+ /**
+ * Whether the top of the viewport on the target page should
+ * be changed.
+ *
+ * \see top()
+ */
bool isChangeTop() const;
+ /**
+ * Whether the zoom level should be changed.
+ *
+ * \see zoom()
+ */
bool isChangeZoom() const;
/**
@@ -94,6 +138,9 @@ class POPPLER_QT4_EXPORT LinkDestination
*/
QString toString() const;
+ /**
+ * Assignment operator.
+ */
LinkDestination& operator=(const LinkDestination &other);
private:
@@ -110,12 +157,13 @@ class POPPLER_QT4_EXPORT LinkDestination
class POPPLER_QT4_EXPORT Link
{
public:
+ /// \cond PRIVATE
Link( const QRectF &linkArea );
+ /// \endcond
/**
* The possible kinds of link.
*
- * \internal
* Inherited classes must return an unique identifier
*/
enum LinkType
@@ -160,7 +208,14 @@ class POPPLER_QT4_EXPORT Link
};
-/** Goto: a viewport and maybe a reference to an external filename **/
+/**
+ * \brief Viewport reaching request.
+ *
+ * With a LinkGoto link, the document requests the specified viewport to be
+ * reached (aka, displayed in a viewer). Furthermore, if a file name is specified,
+ * then the destination refers to that document (and not to the document the
+ * current LinkGoto belongs to).
+ */
class POPPLER_QT4_EXPORT LinkGoto : public Link
{
public:
@@ -188,6 +243,9 @@ class POPPLER_QT4_EXPORT LinkGoto : public Link
* or an empty string in case it refers to the current document.
*/
QString fileName() const;
+ /**
+ * The destination to reach.
+ */
LinkDestination destination() const;
LinkType linkType() const;
@@ -196,7 +254,14 @@ class POPPLER_QT4_EXPORT LinkGoto : public Link
Q_DISABLE_COPY( LinkGoto )
};
-/** Execute: filename and parameters to execute **/
+/**
+ * \brief Generic execution request.
+ *
+ * The LinkExecute link represent a "file name" execution request. The result
+ * depends on the \link fileName() file name\endlink:
+ * - if it is a document, then it is requested to be open
+ * - otherwise, it represents an executable to be run with the specified parameters
+ */
class POPPLER_QT4_EXPORT LinkExecute : public Link
{
public:
@@ -205,8 +270,7 @@ class POPPLER_QT4_EXPORT LinkExecute : public Link
*/
QString fileName() const;
/**
- * If \ref fileName() represents a command, then this can hold
- * the various parameters for it.
+ * The parameters for the command.
*/
QString parameters() const;
@@ -229,7 +293,14 @@ class POPPLER_QT4_EXPORT LinkExecute : public Link
Q_DISABLE_COPY( LinkExecute )
};
-/** Browse: an URL to open, ranging from 'http://' to 'mailto:', etc. **/
+/**
+ * \brief An URL to browse.
+ *
+ * The LinkBrowse link holds a URL (eg 'http://poppler.freedesktop.org',
+ * 'mailto:john at some.org', etc) to be open.
+ *
+ * The format of the URL is specified by RFC 2396 (http://www.ietf.org/rfc/rfc2396.txt)
+ */
class POPPLER_QT4_EXPORT LinkBrowse : public Link
{
public:
@@ -256,7 +327,12 @@ class POPPLER_QT4_EXPORT LinkBrowse : public Link
Q_DISABLE_COPY( LinkBrowse )
};
-/** Action: contains an action to perform on document / viewer **/
+/**
+ * \brief "Standard" action request.
+ *
+ * The LinkAction class represents a link that request a "standard" action
+ * to be performed by the viewer on the displayed document.
+ */
class POPPLER_QT4_EXPORT LinkAction : public Link
{
public:
diff --git a/qt4/src/poppler-qt4.h b/qt4/src/poppler-qt4.h
index c14a627..6ca7074 100644
--- a/qt4/src/poppler-qt4.h
+++ b/qt4/src/poppler-qt4.h
@@ -294,7 +294,12 @@ namespace Poppler {
/**
- Page within a PDF document
+ \brief A page in a document.
+
+ The Page class represents a single page within a PDF document.
+
+ You cannot construct a Page directly, but you have to use the Document
+ functions that return a new Page out of an index or a label.
*/
class POPPLER_QT4_EXPORT Page {
friend class Document;
@@ -322,8 +327,8 @@ namespace Poppler {
};
/**
- Render the page to a QImage using the current Document renderer
- (see Document::renderBackend())
+ Render the page to a QImage using the current
+ \link Document::renderBackend() Document renderer\endlink.
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
@@ -351,9 +356,6 @@ namespace Poppler {
\param rotate how to rotate the page
- \note if the current Document renderer does not appear among the
- Document::availableRenderBackends(), the result is \em always a null QImage.
-
\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.
@@ -506,9 +508,44 @@ namespace Poppler {
};
/**
- PDF document
+ \brief PDF document.
+
+ The Document class represents a PDF document: its pages, and all the global
+ properties, metadata, etc.
+
+ \section ownership Ownership of the returned objects
+
+ All the functions that returns class pointers create new object, and the
+ responsability of those is given to the callee.
+
+ The only exception is \link Poppler::Page::transition() Page::transition()\endlink.
+
+ \section document-loading Loading
+
+ To get a Document, you have to load it via the load() & loadFromData()
+ functions.
+
+ In all the functions that have passwords as arguments, they \b must be Latin1
+ encoded. If you have a password that is a UTF-8 string, you need to use
+ QString::toLatin1() (or similar) to convert the password first.
+ If you have a UTF-8 character array, consider converting it to a QString first
+ (QString::fromUtf8(), or similar) before converting to Latin1 encoding.
+
+ \section document-rendering Rendering
+
+ To render pages of a document, you have different Document functions to set
+ various options.
+
+ \subsection document-rendering-backend Backends
- A document potentially contains multiple Pages
+ %Poppler offers a different backends for rendering the pages. Currently
+ there two backends (see #RenderBackend), but only the Splash engine works
+ well and has been tested.
+
+ The available rendering backends can be discovered via availableRenderBackends().
+ The current rendering backend can be changed using setRenderBackend().
+ Please note that setting a backend not listed in the available ones
+ will always result in null QImage's.
*/
class POPPLER_QT4_EXPORT Document {
friend class Page;
@@ -565,16 +602,12 @@ namespace Poppler {
Load the document from a file on disk
\param filePath the name (and path, if required) of the file to load
- \param ownerPassword the owner password to use in loading the file.
- \param userPassword the user ("open") password to use in loading the file
-
- \return NULL on error
+ \param ownerPassword the Latin1-encoded owner password to use in
+ loading the file
+ \param userPassword the Latin1-encoded user ("open") password
+ to use in loading the file
- \note Passwords must be Latin1 encoded. If you have a password that is
- a UTF8 string, you need to use QString::toLatin1() (or similar) to convert
- the password first. If you have a UTF8 character array, consider
- converting it to a QString first (QString::fromUtf8(), or similar) before
- converting to Latin1 encoding.
+ \return the loaded document, or NULL on error
\note The caller owns the pointer to Document, and this should
be deleted when no longer required.
@@ -592,17 +625,18 @@ namespace Poppler {
\param fileContents the file contents. They are copied so there is no need
to keep the byte array around for the full life time of
the document.
- \param ownerPassword the owner password to use in loading the file.
- \param userPassword the user ("open") password to use in loading the file
+ \param ownerPassword the Latin1-encoded owner password to use in
+ loading the file
+ \param userPassword the Latin1-encoded user ("open") password
+ to use in loading the file
- \note Passwords must be Latin1 encoded. If you have a password that is
- a UTF8 string, you need to use QString::toLatin1() (or similar) to convert
- the password first. If you have a UTF8 character array, consider
- converting it to a QString first (QString::fromUtf8(), or similar) before
- converting to Latin1 encoding.
+ \return the loaded document, or NULL on error
\note The caller owns the pointer to Document, and this should
be deleted when no longer required.
+
+ \warning The returning document may be locked if a password is required
+ to open the file, and one is not provided (as the userPassword).
\since 0.6
*/
@@ -624,9 +658,9 @@ namespace Poppler {
\overload
- The intent is that you can pass in a label like "ix" and
+ The intent is that you can pass in a label like \c "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
+ contents), or pass in \c "1" and get the page that the user
expects (which might not be the first page, if there is a
title page and a table of contents).
@@ -656,14 +690,10 @@ namespace Poppler {
/**
Provide the passwords required to unlock the document
- \param ownerPassword the owner password to use in loading the file.
- \param userPassword the user ("open") password to use in loading the file
-
- \note Passwords must be Latin1 encoded. If you have a password that is
- a UTF8 string, you need to use QString::toLatin1() (or similar) to convert
- the password first. If you have a UTF8 character array, consider
- converting it to a QString first (QString::fromUtf8(), or similar) before
- converting to Latin1 encoding.
+ \param ownerPassword the Latin1-encoded owner password to use in
+ loading the file
+ \param userPassword the Latin1-encoded user ("open") password
+ to use in loading the file
*/
bool unlock(const QByteArray &ownerPassword, const QByteArray &userPassword);
@@ -846,15 +876,31 @@ QString subject = m_doc->info("Subject");
In the tree the tag name is the 'screen' name of the entry. A tag can have
attributes. Here follows the list of tag attributes with meaning:
- Destination: A string description of the referred destination
- - DestinationName: A 'named reference' to the viewport that must be converted
- using \p linkDestination( \em destination_name )
+ - DestinationName: A 'named reference' to the viewport
- ExternalFileName: A link to a external filename
- Open: A bool value that tells whether the subbranch of the item is open or not
+ Resolving the final destination for each item can be done in the following way:
+ - first, checking for 'Destination': if not empty, then a LinkDestination
+ can be constructed straight with it
+ - as second step, if the 'DestinationName' is not empty, then the destination
+ can be resolved using linkDestination()
+
+ Note also that if 'ExternalFileName' is not emtpy, then the destination refers
+ to that document (and not to the current one).
+
\returns the TOC, or NULL if the Document does not have one
*/
QDomDocument *toc() const;
+ /**
+ Tries to resolve the named destination \p name.
+
+ \note this operation starts a search through the whole document
+
+ \returns a new LinkDestination object if the named destination was
+ actually found, or NULL otherwise
+ */
LinkDestination *linkDestination( const QString &name );
/**
@@ -873,9 +919,6 @@ QString subject = m_doc->info("Subject");
/**
Sets the backend used to render the pages.
- \note setting a rendering backend that does not appear in the
- availableRenderBackends() will always result in null QImage's.
-
\param backend the new rendering backend
\since 0.6
commit e2461c9aa4d74b5511621d7222979948e31541ad
Author: Pino Toscano <pino at kde.org>
Date: Sun Sep 28 18:07:25 2008 +0200
[Qt4] Activate the 'printing' flag by default in the PSConverter.
diff --git a/qt4/src/poppler-ps-converter.cc b/qt4/src/poppler-ps-converter.cc
index c805a40..ea3887d 100644
--- a/qt4/src/poppler-ps-converter.cc
+++ b/qt4/src/poppler-ps-converter.cc
@@ -54,7 +54,7 @@ PSConverterPrivate::PSConverterPrivate()
: BaseConverterPrivate(),
hDPI(72), vDPI(72), rotate(0), paperWidth(-1), paperHeight(-1),
marginRight(0), marginBottom(0), marginLeft(0), marginTop(0),
- opts(0)
+ opts(PSConverter::Printing)
{
}
diff --git a/qt4/src/poppler-qt4.h b/qt4/src/poppler-qt4.h
index 12634a7..c14a627 100644
--- a/qt4/src/poppler-qt4.h
+++ b/qt4/src/poppler-qt4.h
@@ -1143,6 +1143,8 @@ height = dummy.height();
/**
The currently set options for the PS export.
+ The default flags are: Printing.
+
\since 0.10
*/
PSOptions psOptions() const;
More information about the poppler
mailing list