From 7a54d93487f4097c0950bbb7063162a104661e94 Mon Sep 17 00:00:00 2001 From: Shawn Rutledge Date: Thu, 10 Feb 2022 13:25:23 +0100 Subject: doc: begin adding docs for MultiPageView component and example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Task-number: QTBUG-81560 Change-Id: I062e022a97c146e9a746b6d6358868bfe0c0a7d7 Reviewed-by: Topi Reiniö (cherry picked from commit 8018a4cbce8f01add2aa011b3448516cb6ea92ef) Reviewed-by: Shawn Rutledge --- examples/pdf/multipage/doc/src/multipage.qdoc | 79 +++++++++ examples/pdf/multipage/viewer.qml | 2 +- src/pdf/doc/images/multipageviewer.png | Bin 0 -> 55795 bytes src/pdf/doc/qtpdf.qdocconf | 1 + src/pdf/doc/snippets/multipageview.qml | 8 + src/pdfquick/qml/PdfMultiPageView.qml | 224 +++++++++++++++++++++++++- 6 files changed, 310 insertions(+), 4 deletions(-) create mode 100644 examples/pdf/multipage/doc/src/multipage.qdoc create mode 100644 src/pdf/doc/images/multipageviewer.png create mode 100644 src/pdf/doc/snippets/multipageview.qml diff --git a/examples/pdf/multipage/doc/src/multipage.qdoc b/examples/pdf/multipage/doc/src/multipage.qdoc new file mode 100644 index 000000000..ecb8127b1 --- /dev/null +++ b/examples/pdf/multipage/doc/src/multipage.qdoc @@ -0,0 +1,79 @@ +/**************************************************************************** +** +** Copyright (C) 2022 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example multipage + \ingroup qtpdf-examples + + \title PDF Multipage Viewer Example + \brief A PDF viewer that allows scrolling through the pages. + + \image multipageviewer.png + + \e {PDF Multipage Viewer} demonstrates how to use the PdfMultiPageView + component to render PDF documents and search for text in them. + + \include examples-run.qdocinc + + \section1 Creating the Main Window + + Instantiate an \l ApplicationWindow, bind its title to the title of the + PDF document, and create a toolbar: + + \quotefromfile multipage/viewer.qml + \skipto ApplicationWindow + \printuntil rightMargin + + The toolbar has buttons for most of the common actions: + + \printuntil ZoomOut + + Declare a PdfDocument and bind the \c status property and + \c passwordRequired signal to inform the user when an error occurs or a + password is required: + + \skipto onAccepted + \skipto Dialog + \printto PdfMultiPageView + + Add the main component, PdfMultiPageView: + + \printto onCurrentPageChanged + \printto Drawer + + A \l Drawer holds a ListView to show search results from the + \l {PdfMultiPageView::searchModel}{searchModel}: + + \printto ToolBar + + Finally, add a second toolbar as a footer, to hold the search field, + search up/down buttons and some status information: + + \printuntil + + \section1 Files and Attributions +*/ diff --git a/examples/pdf/multipage/viewer.qml b/examples/pdf/multipage/viewer.qml index a4f3234dd..7c883a02b 100644 --- a/examples/pdf/multipage/viewer.qml +++ b/examples/pdf/multipage/viewer.qml @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2020 The Qt Company Ltd. +** Copyright (C) 2022 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the examples of the Qt Toolkit. diff --git a/src/pdf/doc/images/multipageviewer.png b/src/pdf/doc/images/multipageviewer.png new file mode 100644 index 000000000..f6ebd2d83 Binary files /dev/null and b/src/pdf/doc/images/multipageviewer.png differ diff --git a/src/pdf/doc/qtpdf.qdocconf b/src/pdf/doc/qtpdf.qdocconf index 75d41af1d..24f7d8b51 100644 --- a/src/pdf/doc/qtpdf.qdocconf +++ b/src/pdf/doc/qtpdf.qdocconf @@ -44,6 +44,7 @@ sourcedirs += ../ \ ../../pdfquick exampledirs += ../../../examples/pdfwidgets \ + ../../../examples/pdf \ snippets/ # add a generic thumbnail for an example that has no \image in its doc diff --git a/src/pdf/doc/snippets/multipageview.qml b/src/pdf/doc/snippets/multipageview.qml new file mode 100644 index 000000000..ee695c03a --- /dev/null +++ b/src/pdf/doc/snippets/multipageview.qml @@ -0,0 +1,8 @@ +//! [0] +import QtQuick +import QtQuick.Pdf + +PdfMultiPageView { + document: PdfDocument { source: "my.pdf" } +} +//! [0] diff --git a/src/pdfquick/qml/PdfMultiPageView.qml b/src/pdfquick/qml/PdfMultiPageView.qml index ff4a4ed55..a787899d8 100644 --- a/src/pdfquick/qml/PdfMultiPageView.qml +++ b/src/pdfquick/qml/PdfMultiPageView.qml @@ -43,18 +43,74 @@ import QtQuick.Pdf 5.15 import QtQuick.Shapes 1.14 import QtQuick.Window 2.14 +/*! + \qmltype PdfMultiPageView + \inqmlmodule QtQuick.Pdf + \brief A complete PDF viewer component for scrolling through multiple pages. + + PdfMultiPageView provides a PDF viewer component that offers a user + experience similar to many common PDF viewer applications. It supports + flicking through the pages in the entire document, with narrow gaps between + the page images. + + PdfMultiPageView also supports selecting text and copying it to the + clipboard, zooming in and out, clicking an internal link to jump to another + section in the document, rotating the view, and searching for text. The + \l {PDF Multipage Viewer Example} demonstrates how to use these features + in an application. + + The implementation is a QML assembly of smaller building blocks that are + available separately. In case you want to make changes in your own version + of this component, you can copy the QML, which is installed into the + \c QtQuick/Pdf/qml module directory, and modify it as needed. + + \sa PdfPageView, PdfScrollablePageView, PdfStyle +*/ Item { - // public API - // TODO 5.15: required property - property var document: undefined property bool debug: false + // -------------------------------- + // public API + + /*! + \qmlproperty PdfDocument PdfMultiPageView::document + + A PdfDocument object with a valid \c source URL is required: + + \snippet multipageview.qml 0 + */ + required property PdfDocument document + + /*! + \qmlproperty PdfDocument PdfMultiPageView::selectedText + + The selected text. + */ property string selectedText + + /*! + \qmlmethod void PdfMultiPageView::selectAll() + + Selects all the text on the \l {currentPage}{current page}, and makes it + available as the system \l {QClipboard::Selection}{selection} on systems + that support that feature. + + \sa copySelectionToClipboard() + */ function selectAll() { var currentItem = tableHelper.itemAtCell(tableHelper.cellAtPos(root.width / 2, root.height / 2)) if (currentItem) currentItem.selection.selectAll() } + + /*! + \qmlmethod void PdfMultiPageView::copySelectionToClipboard() + + Copies the selected text (if any) to the + \l {QClipboard::Clipboard}{system clipboard}. + + \sa selectAll() + */ function copySelectionToClipboard() { var currentItem = tableHelper.itemAtCell(tableHelper.cellAtPos(root.width / 2, root.height / 2)) if (debug) @@ -63,17 +119,89 @@ Item { currentItem.selection.copyToClipboard() } + // -------------------------------- // page navigation + + /*! + \qmlproperty int PdfMultiPageView::currentPage + \readonly + + This property holds the zero-based page number of the page visible in the + scrollable view. If there is no current page, it holds -1. + + This property is read-only, and is typically used in a binding (or + \c onCurrentPageChanged script) to update the part of the user interface + that shows the current page number, such as a \l SpinBox. + + \sa PdfNavigationStack::currentPage + */ property alias currentPage: navigationStack.currentPage + + /*! + \qmlproperty bool PdfMultiPageView::backEnabled + \readonly + + This property indicates if it is possible to go back in the navigation + history to a previous-viewed page. + + \sa PdfNavigationStack::backAvailable, back() + */ property alias backEnabled: navigationStack.backAvailable + + /*! + \qmlproperty bool PdfMultiPageView::forwardEnabled + \readonly + + This property indicates if it is possible to go to next location in the + navigation history. + + \sa PdfNavigationStack::forwardAvailable, forward() + */ property alias forwardEnabled: navigationStack.forwardAvailable + + /*! + \qmlmethod void PdfMultiPageView::back() + + Scrolls the view back to the previous page that the user visited most + recently; or does nothing if there is no previous location on the + navigation stack. + + \sa PdfNavigationStack::back(), currentPage, backEnabled + */ function back() { navigationStack.back() } + + /*! + \qmlmethod void PdfMultiPageView::forward() + + Scrolls the view to the page that the user was viewing when the back() + method was called; or does nothing if there is no "next" location on the + navigation stack. + + \sa PdfNavigationStack::forward(), currentPage + */ function forward() { navigationStack.forward() } + + /*! + \qmlmethod void PdfMultiPageView::goToPage(int page) + + Scrolls the view to the given \a page number, if possible. + + \sa PdfNavigationStack::push(), currentPage + */ function goToPage(page) { if (page === navigationStack.currentPage) return goToLocation(page, Qt.point(-1, -1), 0) } + + /*! + \qmlmethod void PdfMultiPageView::goToLocation(int page, point location, real zoom) + + Scrolls the view to the \a location on the \a page, if possible, + and sets the \a zoom level. + + \sa PdfNavigationStack::push(), currentPage + */ function goToLocation(page, location, zoom) { if (zoom > 0) { navigationStack.jumping = true // don't call navigationStack.update() because we will push() instead @@ -84,15 +212,69 @@ Item { navigationStack.push(page, location, zoom) // actually jump } property vector2d jumpLocationMargin: Qt.vector2d(10, 10) // px from top-left corner + + /*! + \qmlproperty int PdfMultiPageView::currentPageRenderingStatus + + This property holds the \l {QtQuick::Image::status}{rendering status} of + the \l {currentPage}{current page}. + + \sa PdfPageImage::status + */ property int currentPageRenderingStatus: Image.Null + // -------------------------------- // page scaling + + /*! + \qmlproperty real PdfMultiPageView::renderScale + + This property holds the ratio of pixels to points. The default is \c 1, + meaning one point (1/72 of an inch) equals 1 logical pixel. + + \sa PdfPageImage::status + */ property real renderScale: 1 + + /*! + \qmlproperty real PdfMultiPageView::pageRotation + + This property holds the clockwise rotation of the pages. + + The default value is \c 0 degrees (that is, no rotation relative to the + orientation of the pages as stored in the PDF file). + + \sa PdfPageImage::rotation + */ property real pageRotation: 0 + + /*! + \qmlmethod void PdfMultiPageView::resetScale() + + Sets \l renderScale back to its default value of \c 1. + */ function resetScale() { root.renderScale = 1 } + + /*! + \qmlmethod void PdfMultiPageView::scaleToWidth(real width, real height) + + Sets \l renderScale such that the width of the first page will fit into a + viewport with the given \a width and \a height. If the page is not rotated, + it will be scaled so that its width fits \a width. If it is rotated +/- 90 + degrees, it will be scaled so that its width fits \a height. + */ function scaleToWidth(width, height) { root.renderScale = width / (tableView.rot90 ? tableView.firstPagePointSize.height : tableView.firstPagePointSize.width) } + + /*! + \qmlmethod void PdfMultiPageView::scaleToPage(real width, real height) + + Sets \l renderScale such that the whole first page will fit into a viewport + with the given \a width and \a height. The resulting \l renderScale depends + on \l pageRotation: the page will fit into the viewport at a larger size if + it is first rotated to have a matching aspect ratio. + */ function scaleToPage(width, height) { var windowAspect = width / height var pageAspect = tableView.firstPagePointSize.width / tableView.firstPagePointSize.height @@ -111,10 +293,46 @@ Item { } } + // -------------------------------- // text search + + /*! + \qmlproperty PdfSearchModel PdfMultiPageView::searchModel + + This property holds a PdfSearchModel containing the list of search results + for a given \l searchString. + + \sa PdfSearchModel + */ property alias searchModel: searchModel + + /*! + \qmlproperty string PdfMultiPageView::searchString + + This property holds the search string that the user may choose to search + for. It is typically used in a binding to the + \l {QtQuick.Controls::TextField::text}{text} property of a TextField. + + \sa searchModel + */ property alias searchString: searchModel.searchString + + /*! + \qmlmethod void PdfMultiPageView::searchBack() + + Decrements the + \l{PdfSearchModel::currentResult}{searchModel's current result} + so that the view will jump to the previous search result. + */ function searchBack() { --searchModel.currentResult } + + /*! + \qmlmethod void PdfMultiPageView::searchForward() + + Increments the + \l{PdfSearchModel::currentResult}{searchModel's current result} + so that the view will jump to the next search result. + */ function searchForward() { ++searchModel.currentResult } id: root -- cgit v1.2.3