README.md
1Experimental Multi-Page PDF Viewer
2==================================
3
4This branch contains an work-in-progress PDF viewer that is intended to replace
5the `PDFWidget` class in `src/PDFDocument.cpp`. Only the files in `src` are
6intended to be merged into the TeXworks tree---everything else is part of test
7apps that streamline the prototyping process.
8
9Upon launching, the test app uses the classes contained in the `src` folder to
10display a copy of the PGF manual. The PGF manual was chosen as a test case
11because:
12
13 - It was produced by TeX.
14 - It is extensively cross-referenced with hyperlinks.
15 - It is quite large and has many complex layouts. This is a good stress test
16 of rendering performance.
17
18
19Things Needed to Build
20======================
21
22CMake is used to build a library containing the rendering code and test apps
23that use different backends.
24
25The following libraries are required by all targets:
26
27 - qt
28 - zlib
29 - freetype2
30
31For the Poppler backend, the following components are needed:
32
33 - poppler with poppler-qt4 or poppler-qt5
34
35For the MuPDF backend, the following components are needed:
36
37 - jpeg
38 - openjpeg
39 - jbig2dec
40 - mupdf
41
42By default, CMake will look for Poppler and produce the `poppler_viewer`
43executable. To enable MuPDF and the `mupdf_viewer`, add `-DWITH_MUDPF=YES` to
44the options passed to `cmake`.
45
46For using poppler-qt5, poppler >= 0.23.3 and Qt5 are required. You can set
47DESIRED_QT_VERSION to force a specific Qt version (e.g., Qt5).
48
49Building on Windows
50===================
51
52Windows builds can be accomplished using MinGW, MSYS and CMake. Assuming Qt is
53installed and the required dependencies have been built and installed to
54`/c/opt/texworks`, the following steps can be invoked from a MSYS shell to
55build the project:
56
57 mkdir build
58 cd build
59 cmake .. -G "MSYS Makefiles" -DCMAKE_PREFIX_PATH=/c/opt/texworks
60
61 make
62
63
64TODO
65====
66### Required
67 - Fix FIXMEs
68 - ~~context menu~~
69 - ~~Highlighting! (to show syncing destination, search results, etc.)~~ __DONE__
70 - ~~Port scripting-related functions from Tw (if any)~~
71 - ~~Possibility to reload current file (e.g., if it changed on disk); note that
72 this requires some reconsideration of memory management, as Page object
73 could change, which would have to be propagated upwards to every object
74 holding a pointer to them (e.g., PDFPageGraphicsItem)~~ __DONE__
75 - ~~Add a PDFDocumentWidget, derived from PDFDocumentView, which encapsulates the
76 scene and provides, e.g., a load() function for ease of use (similar to what
77 Qt does, see QTreeView vs. QTreeWidget)~~ __DONE__
78 - ~~Make program translatable; this probably entails creating a (dummy) Qt .pro
79 file so we can use the normal Qt linguist approach~~ __DONE__
80 - ~~Properly namespace the code~~ __DONE__
81 - ~~Handling of encrypted/password protected files (this needs to be handled
82 during loading; accessing some functions (e.g., for rendering) in a locked
83 document crashes the program)~~ __DONE__
84 - ~~Ensure temporary "rendering" images are always replaced. Thought this was
85 fixed by e9c7be11df5bfe507585fea889e8b588b4431fff, but the bug is still
86 present.~~ __DONE__
87 - ~~Possibly simplify page processing request generation. Rational: Right now,
88 requestLoadLinks, requestRenderPage, and addPageProcessingRequest are all
89 called from the main thread, if I understood threading correctly.
90 Consequently, the page processing request object should live in the main
91 thread as well (but is accessed only from the worked thread). If that is
92 correct, all the moving of objects is superfluous as well.~~ __DONE__
93 - ~~Clicking on an item in the ToC that lies after the current viewport position
94 moves the view such that a small band of the page in question is visible at
95 the bottom of the screen---but we should see that page fill the entire screen
96 Note: this only applies of no viewport setting is associated with the toc
97 item~~ __DONE__
98 - ~~Fix MuPDF when using non-English numeric locale~~ __DONE__
99 - ~~Icons (add icons for page modes, make marquee zoom icon consistent with
100 other icons)~~ __DONE__
101 - ~~Turn PDFViewer into a more general test case (loading of arbitrary files,
102 etc.)~~ __DONE__
103 - ~~Program segfaults if a page is destroyed while a render request is active~~
104 __DONE__
105 - ~~GotoPage should not center on page~~ __DONE__
106 - ~~zoom/hand tools~~ __DONE__
107 - ~~ctrl+mousewheel should zoom~~ __DONE__
108 - ~~maquee zoom (requested by Philip Taylor)~~ __DONE__
109 - ~~Flesh out link support~~ __DONE__
110 - ~~Add some loading indicators so that users know something is happening in the
111 background when pages are blank or blurry~~ __DONE__
112 - ~~scrolling beyond edge at single page mode (mouse wheel/up/down)~~ __DONE__
113 - ~~disallow keyboard events in document view while magnifier is shown (otherwise
114 one could scroll the canvas without properly adjusting the magnifier)~~ __DONE__
115 - ~~SyncTeX with signals and slots~~ __DONE__ (actually invoking SyncTeX must
116 be implemented separate from the viewer)
117 - ~~fit to width/page/~~ __DONE__
118 - ~~PgDn should scroll one viewport height~~ __DONE__
119 - ~~draw frame around magnifying glass (requested by Reinhard Kotucha)~~ __DONE__
120 - ~~Control memory usage through caching and zoom throttling~~ __DONE__
121 - ~~Don't show mouse cursor while using the magnifier~~ __DONE__
122
123### Wishlist
124 - Add automated (unit) tests (presumably using the QtTest framework as that
125 directly supports generating and monitoring Qt events) __STARTED__
126 - Speed up magnifier; in Tw, it seems much more responsive. This might be due
127 to using centerOn in PDFDocumentMagnifierView::setPosition but needs closer
128 investigation
129 - possibility to abort render requests when page moves out of view (is there a
130 way to avoid going through all pages at each scroll event?)
131 - annotations (popup window)
132 - make the magnifying glass a top-level window (so it can extend outside the
133 main view's window boundaries) (requested by Reinhard Kotucha)
134 - rulers (in main window, and attached to magnifying glass)
135 - or ~~measuring tool~~ __DONE__
136 - Split view???
137 - Provide additional info, e.g. through QDockWidget. ~~Annotations,~~
138 thumbnails (?). __STARTED__
139 - Printing.
140 - Derive zoom icons from Tango instead of from Qt
141 - Presentation mode __STARTED__
142 - ~~should display all pages in fit-to-window mode~~ __DONE__
143 - ~~must render all pages completely before switching to them~~ __DONE__
144 - full screen
145 - ~~transition support?~~ __DONE__
146 - save page as image (subject to permissions)
147 - ~~selecting (and copying) text (subject to permissions)~~ __DONE__
148 - selecting (and copying/saving) images (subject to permissions)
149 - ~~Provide a grayscale mode~~ __DONE__
150 - ~~Implement text search for PDF files.~~ __DONE__
151 - ~~Hitting PgUp at top of document or PgDn at bottom moves to the right~~
152 __DONE__
153