Changeset View
Standalone View
part.h
Show First 20 Lines • Show All 95 Lines • ▼ Show 20 Line(s) | 95 | { | |||
---|---|---|---|---|---|
96 | UnknownEmbedMode, | 96 | UnknownEmbedMode, | ||
97 | NativeShellMode, // embedded in the native Okular' shell | 97 | NativeShellMode, // embedded in the native Okular' shell | ||
98 | PrintPreviewMode, // embedded to show the print preview of a document | 98 | PrintPreviewMode, // embedded to show the print preview of a document | ||
99 | KHTMLPartMode, // embedded in KHTML | 99 | KHTMLPartMode, // embedded in KHTML | ||
100 | ViewerWidgetMode // the part acts as a widget that can display all kinds of documents | 100 | ViewerWidgetMode // the part acts as a widget that can display all kinds of documents | ||
101 | }; | 101 | }; | ||
102 | 102 | | |||
103 | /** | 103 | /** | ||
104 | * @short Main Part | ||||
105 | * | ||||
104 | * This is a "Part". It that does all the real work in a KPart | 106 | * This is a "Part". It that does all the real work in a KPart | ||
105 | * application. | 107 | * application. | ||
106 | * | 108 | * | ||
107 | * @short Main Part | 109 | * @par Opening a Document | ||
110 | * @parblock | ||||
111 | * This class provides two public methods to open documents, which will call openUrl(). | ||||
112 | * - openDocument( const QString &url ) | ||||
113 | * Is a slot accessible from D-Bus and opens a document from the URL @p url. | ||||
114 | * Use this method to process user entered URLs, because they are parsed tolerantly. | ||||
115 | * - openDocument( const QString &url, uint page ) | ||||
116 | * Is not accessible from D-Bus and not a slot, but allows to specify the page explicitely. | ||||
117 | * | ||||
118 | * Internally, these methods handle the document opening. | ||||
119 | * - openUrl( const QUrl &url ) | ||||
120 | * Overrides ReadOnlyPart::openUrl( const QUrl& ) to redirect to the following method: | ||||
aacid: Do we really need to document a 1 line function? | |||||
openUrl() is the function which is usually used by Parts to open something. Someone (me) who wants to understand how documents are opened will want to know what will happen to a call to this function. It doesn’t need do be documentation of this function, just describing what will happen to the usual call is enough. In the documentation of this function, I consider the following approiate: davidhurka: openUrl() is the function which is usually used by Parts to open something. Someone (me) who… | |||||
the thing is, that's not true, calling openUrl is fine, it's what the okular shell does, no? aacid: the thing is, that's not true, calling openUrl is fine, it's what the okular shell does, no? | |||||
Yes and yes. The shell has an URL that doesn’t need to be tolerantly parsed. The purpose of openDocument(QUrl) is to be called by other applications, where the quality of the URL is not defined (only to be expected when Okular::Part is not used though the KPart interface), right? davidhurka: Yes and yes. The shell has an URL that doesn’t need to be tolerantly parsed.
The purpose of… | |||||
121 | * - openUrl( const QUrl &url, bool swapInsteadOfOpening ) | ||||
122 | * Uses the original implementation of ReadOnlyPart::openUrl( const QUrl& ), | ||||
123 | * but allows to reload the file without interrupting the viewer. | ||||
aacid: Can you explain what you mean with that sentence about reload? | |||||
The Reload action (F5) also reloads the UI, but SaveAs doesn’t. It also reloads the document, so it is backed by the newly saved file. It uses swapInsteadOfOpening to achieve that. At least that is how I understand it. davidhurka: The Reload action (F5) also reloads the UI, but SaveAs doesn’t. It also reloads the document… | |||||
124 | * - openFile() | ||||
125 | * Called by the original implementation of ReadOnlyPart::openUrl( const QUrl& ). | ||||
aacid: original seems a strange word to use here | |||||
davidhurka: Ok, will change that. | |||||
126 | * Tries to determine the mimetype, and handles UI updating. | ||||
127 | * - doOpenFile( const QMimeType &mime, const QString &fileNameToOpen, bool *out_isCompressedFile ) | ||||
128 | * Called by openFile(), with exacty one mimetype. | ||||
129 | * To actually open the file, this calls Document, which will get the correct Generator for the mimetype. | ||||
130 | * | ||||
I'm really sorry but i don't see any value in this documentation here. You just described the calling flow. This is something anyone with a debugger or a nice IDE can do. And it is very easy this will get out of sync once someone renames a method. Please try to convince me why having this is useful. aacid: I'm really sorry but i don't see any value in this documentation here.
You just described the… | |||||
I needed this calling flow to understand how Okular handles document opening. For someone else (don’t know who that could be, someone of the future...), this could give an overview. And that is what I consider the purpose of documentation. People who prever a debugger or the capabilities of an IDE won’t neccessarily need that. I think it is save to document this, because many of these functions are exposed and probably won’t be renamend. doOpenFile() sounds a little strange, but is accurate. The following three functions will more likely be changed. And they are pretty trivial and simple to understand with a normal IDE, so I’m ok with removing this part. davidhurka: I needed this calling flow to understand how Okular handles document opening. For someone else… | |||||
131 | * Similarly to openDocument(), these protected slots are used for special use cases of opening. They also call openUrl(). | ||||
132 | * - openUrlFromDocument( const QUrl &url ) | ||||
133 | * For inter-document links from within the current document. | ||||
134 | * - openUrlFromBookmarks( const QUrl &url ) | ||||
135 | * For bookmarks from the side panel or the Bookmarks menu. | ||||
136 | * - handleDroppedUrls( const QList< QUrl > &urls ) | ||||
137 | * For URLs which are drag&dropped onto this Parts widget. | ||||
138 | * | ||||
139 | * When the document is opened, it may be decompressed to a temporary file. url() will return that file then, you can use realUrl() to get the URL of the real document file. | ||||
140 | * | ||||
141 | * When a URL is dropped via drag&drop, this Part will open it. | ||||
142 | * @endparblock | ||||
143 | * | ||||
144 | * @par Closing the document | ||||
145 | * Closing the document is less complex. | ||||
146 | * - closeUrl() will close the document. | ||||
147 | * - queryClose() only offers the user to save changes made to the document, but will not close. | ||||
148 | * | ||||
149 | * @par Actions | ||||
150 | * This Part enables and disables its own actions automatically. | ||||
151 | * However, it does not have own Open, Print, and Close actions, these shall be implemented by the parent application. | ||||
152 | * The signals enablePrintAction() and enableCloseAction() can be used to keep their enabled state up to date. | ||||
153 | * | ||||
108 | * @author Wilco Greven <greven@kde.org> | 154 | * @author Wilco Greven <greven@kde.org> | ||
109 | * @version 0.2 | 155 | * @version 0.2 | ||
110 | */ | 156 | */ | ||
111 | class OKULARPART_EXPORT Part : public KParts::ReadWritePart, public Okular::DocumentObserver, public KDocumentViewer, public Okular::ViewerInterface | 157 | class OKULARPART_EXPORT Part : public KParts::ReadWritePart, public Okular::DocumentObserver, public KDocumentViewer, public Okular::ViewerInterface | ||
112 | { | 158 | { | ||
113 | Q_OBJECT | 159 | Q_OBJECT | ||
114 | Q_CLASSINFO("D-Bus Interface", "org.kde.okular") | 160 | Q_CLASSINFO("D-Bus Interface", "org.kde.okular") | ||
115 | Q_INTERFACES(KDocumentViewer) | 161 | Q_INTERFACES(KDocumentViewer) | ||
116 | Q_INTERFACES(Okular::ViewerInterface) | 162 | Q_INTERFACES(Okular::ViewerInterface) | ||
117 | 163 | | |||
118 | friend class PartTest; | 164 | friend class PartTest; | ||
119 | 165 | | |||
120 | public: | 166 | public: | ||
121 | // Default constructor | 167 | // Default constructor | ||
122 | /** | 168 | /** | ||
123 | * If one element of 'args' contains one of the strings "Print/Preview" or "ViewerWidget", | 169 | * @param parentWidget TODO | ||
170 | * @param parent The parent object. | ||||
aacid: parent is an object not a widget ;) | |||||
davidhurka: Oh, right. Changed that. | |||||
171 | * @param args If one element contains one of the strings "Print/Preview" or "ViewerWidget", | ||||
parentWidget is what will be a parent of the Part::widget(), so it can receive QEvents which are not used by the Part? Assuming that, a Part receives its QEvents through its widget(), right? davidhurka: parentWidget is what will be a parent of the Part::widget(), so it can receive QEvents which… | |||||
124 | * the part will be set up in the corresponding mode. Additionally, it is possible to specify | 172 | * the part will be set up in the corresponding mode. Additionally, it is possible to specify | ||
125 | * which config file should be used by adding a string containing "ConfigFileName=<file name>" | 173 | * which config file should be used by adding a string containing "ConfigFileName=\<file name\>" | ||
126 | * to 'args'. | 174 | * to 'args'. | ||
127 | **/ | 175 | **/ | ||
128 | Part(QWidget* parentWidget, QObject* parent, const QVariantList& args); | 176 | Part(QWidget* parentWidget, QObject* parent, const QVariantList& args); | ||
129 | 177 | | |||
130 | // Destructor | 178 | // Destructor | ||
131 | ~Part(); | 179 | ~Part(); | ||
132 | 180 | | |||
133 | // inherited from DocumentObserver | 181 | // inherited from DocumentObserver | ||
134 | void notifySetup( const QVector< Okular::Page * > &pages, int setupFlags ) override; | 182 | void notifySetup( const QVector< Okular::Page * > &pages, int setupFlags ) override; | ||
135 | void notifyViewportChanged( bool smoothMove ) override; | 183 | void notifyViewportChanged( bool smoothMove ) override; | ||
136 | void notifyPageChanged( int page, int flags ) override; | 184 | void notifyPageChanged( int page, int flags ) override; | ||
137 | 185 | | |||
186 | // Reimplemented from KDocumentViewer | ||||
187 | /** | ||||
188 | * Opens a document from the given URL at the given page. | ||||
189 | * | ||||
190 | * @param url Path to the document file. | ||||
191 | * @param page The number of the page, where 1 is the first page. | ||||
davidhurka: What if the fragment of the URL contains a page number? | |||||
aacid: the parameter wins. | |||||
192 | * | ||||
193 | * @return Whether the document was opened successfully. | ||||
194 | */ | ||||
138 | bool openDocument(const QUrl &url, uint page) override; | 195 | bool openDocument(const QUrl &url, uint page) override; | ||
139 | void startPresentation() override; | 196 | void startPresentation() override; | ||
140 | QStringList supportedMimeTypes() const override; | 197 | QStringList supportedMimeTypes() const override; | ||
141 | 198 | | |||
199 | /** | ||||
200 | * If, and only if, the opened document was compressed and needed to be decompressed to a temporary file, | ||||
201 | * this returns the URL of the original, compressed file. | ||||
202 | */ | ||||
142 | QUrl realUrl() const; | 203 | QUrl realUrl() const; | ||
143 | 204 | | |||
205 | /** | ||||
206 | * TODO | ||||
207 | */ | ||||
144 | void showSourceLocation(const QString& fileName, int line, int column, bool showGraphically = true) override; | 208 | void showSourceLocation(const QString& fileName, int line, int column, bool showGraphically = true) override; | ||
This creates a GotoAction and lets m_document “process” it. I still don’t understand how (Goto)Action works and how source locations work. davidhurka: This creates a GotoAction and lets m_document “process” it.
I still don’t understand how… | |||||
145 | void clearLastShownSourceLocation() override; | 209 | void clearLastShownSourceLocation() override; | ||
146 | bool isWatchFileModeEnabled() const override; | 210 | bool isWatchFileModeEnabled() const override; | ||
147 | void setWatchFileModeEnabled(bool enable) override; | 211 | void setWatchFileModeEnabled(bool enable) override; | ||
148 | bool areSourceLocationsShownGraphically() const override; | 212 | bool areSourceLocationsShownGraphically() const override; | ||
149 | void setShowSourceLocationsGraphically(bool show) override; | 213 | void setShowSourceLocationsGraphically(bool show) override; | ||
150 | bool openNewFilesInTabs() const override; | 214 | bool openNewFilesInTabs() const override; | ||
151 | 215 | | |||
152 | public Q_SLOTS: // dbus | 216 | public Q_SLOTS: // dbus | ||
153 | Q_SCRIPTABLE Q_NOREPLY void goToPage(uint page) override; | 217 | Q_SCRIPTABLE Q_NOREPLY void goToPage(uint page) override; | ||
218 | | ||||
219 | /** | ||||
220 | * Opens a document from @p doc, which will tolerantly be parsed as URL. | ||||
221 | * Use this to open a document from an URL which was input by a user. | ||||
222 | */ | ||||
154 | Q_SCRIPTABLE Q_NOREPLY void openDocument( const QString &doc ); | 223 | Q_SCRIPTABLE Q_NOREPLY void openDocument( const QString &doc ); | ||
224 | | ||||
225 | /** | ||||
226 | * Returns the page count of the current document, where 1 is one page. | ||||
227 | * May return 0 in some cases. | ||||
228 | */ | ||||
155 | Q_SCRIPTABLE uint pages(); | 229 | Q_SCRIPTABLE uint pages(); | ||
230 | | ||||
231 | /** | ||||
232 | * Returns the number of the current page, where 1 is the first page. | ||||
233 | * May return 0 in some cases. | ||||
234 | */ | ||||
156 | Q_SCRIPTABLE uint currentPage(); | 235 | Q_SCRIPTABLE uint currentPage(); | ||
236 | | ||||
237 | /** | ||||
238 | * Returns the path to the actually opened file. | ||||
239 | * May be a temporary file, e. g. if the document needed to be decompressed. | ||||
240 | */ | ||||
157 | Q_SCRIPTABLE QString currentDocument(); | 241 | Q_SCRIPTABLE QString currentDocument(); | ||
242 | | ||||
243 | /** | ||||
244 | * Returns the metadata entry for the key @p metaData. | ||||
245 | * | ||||
246 | * @see DocumentInfo | ||||
247 | */ | ||||
158 | Q_SCRIPTABLE QString documentMetaData( const QString &metaData ) const; | 248 | Q_SCRIPTABLE QString documentMetaData( const QString &metaData ) const; | ||
249 | | ||||
250 | /** | ||||
251 | * Opens the viewer configuration dialog (i. e. not the backend configuration dialog). | ||||
252 | */ | ||||
159 | Q_SCRIPTABLE void slotPreferences(); | 253 | Q_SCRIPTABLE void slotPreferences(); | ||
254 | | ||||
255 | /** | ||||
256 | * Shows and focuses the incremental find bar. Also works in presentation mode. | ||||
257 | */ | ||||
160 | Q_SCRIPTABLE void slotFind(); | 258 | Q_SCRIPTABLE void slotFind(); | ||
259 | | ||||
260 | /** | ||||
261 | * Opens the print preview dialog. | ||||
262 | */ | ||||
161 | Q_SCRIPTABLE void slotPrintPreview(); | 263 | Q_SCRIPTABLE void slotPrintPreview(); | ||
162 | Q_SCRIPTABLE void slotPreviousPage(); | 264 | Q_SCRIPTABLE void slotPreviousPage(); | ||
163 | Q_SCRIPTABLE void slotNextPage(); | 265 | Q_SCRIPTABLE void slotNextPage(); | ||
164 | Q_SCRIPTABLE void slotGotoFirst(); | 266 | Q_SCRIPTABLE void slotGotoFirst(); | ||
165 | Q_SCRIPTABLE void slotGotoLast(); | 267 | Q_SCRIPTABLE void slotGotoLast(); | ||
268 | | ||||
269 | /** | ||||
270 | * Turns presentation mode on or off. | ||||
271 | * Creates or deletes the presentation widget as needed. | ||||
272 | */ | ||||
166 | Q_SCRIPTABLE void slotTogglePresentation(); | 273 | Q_SCRIPTABLE void slotTogglePresentation(); | ||
274 | | ||||
275 | /** | ||||
276 | * Turns the Change Colors feature on or off. | ||||
277 | * The new state is written to the configuration file. | ||||
278 | */ | ||||
How to set the display used for presentation? It’s possible from the config dialog, but not from D-Bus? davidhurka: How to set the display used for presentation? It’s possible from the config dialog, but not… | |||||
167 | Q_SCRIPTABLE void slotToggleChangeColors(); | 279 | Q_SCRIPTABLE void slotToggleChangeColors(); | ||
280 | | ||||
281 | /** | ||||
282 | * Turns the Change Colors feature on or off. | ||||
283 | * The new state is written to the configuration file. | ||||
284 | */ | ||||
168 | Q_SCRIPTABLE void slotSetChangeColors(bool active); | 285 | Q_SCRIPTABLE void slotSetChangeColors(bool active); | ||
286 | | ||||
287 | /** | ||||
288 | * Reloads the current document, if a document is opened. | ||||
289 | * Continuously tries to reload, if the first try fails. | ||||
290 | */ | ||||
169 | Q_SCRIPTABLE Q_NOREPLY void reload(); | 291 | Q_SCRIPTABLE Q_NOREPLY void reload(); | ||
292 | | ||||
293 | /** | ||||
294 | * Will show the print dialog when the document is loaded the next time. | ||||
295 | */ | ||||
170 | Q_SCRIPTABLE Q_NOREPLY void enableStartWithPrint(); | 296 | Q_SCRIPTABLE Q_NOREPLY void enableStartWithPrint(); | ||
297 | | ||||
298 | /** | ||||
299 | * Will exit the viewer (i. e. this Part) after printing or when the print dialog is closed. | ||||
300 | */ | ||||
171 | Q_SCRIPTABLE Q_NOREPLY void enableExitAfterPrint(); | 301 | Q_SCRIPTABLE Q_NOREPLY void enableExitAfterPrint(); | ||
302 | | ||||
303 | /** | ||||
304 | * Will open the find bar and search for the next occurence of @text, | ||||
305 | * when the document is loaded the next time. | ||||
306 | * Does not necessarily search from the beginning of the document. | ||||
307 | * Does not necessarily search case sensitive. | ||||
308 | * | ||||
309 | * @param text The text to search for. Must not be empty. | ||||
310 | */ | ||||
172 | Q_SCRIPTABLE Q_NOREPLY void enableStartWithFind(const QString &text); | 311 | Q_SCRIPTABLE Q_NOREPLY void enableStartWithFind(const QString &text); | ||
173 | 312 | | |||
174 | Q_SIGNALS: | 313 | Q_SIGNALS: | ||
314 | /** | ||||
315 | * This signal is emitted when the document changes, so it becomes printable or not. | ||||
316 | * Used to enable/disable the Print action in the File menu. | ||||
317 | */ | ||||
175 | void enablePrintAction(bool enable); | 318 | void enablePrintAction(bool enable); | ||
davidhurka: Why doesn’t Part handle the print action itself? | |||||
176 | void openSourceReference(const QString& absFileName, int line, int column); | 319 | void openSourceReference(const QString& absFileName, int line, int column); | ||
177 | void viewerMenuStateChange(bool enabled); | 320 | void viewerMenuStateChange(bool enabled); | ||
321 | | ||||
322 | /** | ||||
323 | * This signal is emitted when a document is loaded, so it can be closed. | ||||
324 | * Used to enable/disable the Close action in the File menu. | ||||
325 | */ | ||||
178 | void enableCloseAction(bool enable); | 326 | void enableCloseAction(bool enable); | ||
327 | | ||||
328 | /** | ||||
329 | * This signal is emitted when a document is loaded. | ||||
330 | * Used to set the tab icon according to the mime type. | ||||
331 | */ | ||||
179 | void mimeTypeChanged(QMimeType mimeType); | 332 | void mimeTypeChanged(QMimeType mimeType); | ||
333 | | ||||
334 | /** | ||||
335 | * This signal is emitted when URLs were dropped on the viewer widget, | ||||
336 | * and this Part is used in the native Shell with tabs enabled. | ||||
337 | */ | ||||
180 | void urlsDropped( const QList<QUrl>& urls ); | 338 | void urlsDropped( const QList<QUrl>& urls ); | ||
339 | | ||||
340 | /** | ||||
341 | * This signal is emitted when the Fit Window to Page action is triggered. | ||||
342 | * | ||||
343 | * @param pageViewPortSize The current size of the viewport, including scrollbars. | ||||
344 | * @param pageSize The size of the area that shall become visible. | ||||
345 | */ | ||||
181 | void fitWindowToPage( const QSize& pageViewPortSize, const QSize& pageSize ); | 346 | void fitWindowToPage( const QSize& pageViewPortSize, const QSize& pageSize ); | ||
What do pageViewPortSize and pageSize mean? Or why are these two important? I don’t understant the slot in Shell. davidhurka: What do `pageViewPortSize` and `pageSize` mean? Or why are //these// two important? I don’t… | |||||
pageViewPortSize is the current viewport size + visible scollbars, davidhurka: pageViewPortSize is the current viewport size + visible scollbars,
and pageSize is the size of… | |||||
182 | 347 | | |||
183 | protected: | 348 | protected: | ||
184 | // reimplemented from KParts::ReadWritePart | 349 | // reimplemented from KParts::ReadWritePart | ||
350 | /** | ||||
351 | * Tries to open a document from localFilePath(). | ||||
352 | * | ||||
353 | * This is called from ReadOnlyPart::openUrl(), which made a local copy available at localFilePath(). | ||||
354 | * | ||||
355 | * If the mimetype was not set with setArguments() before, it will try to guess it. | ||||
356 | * | ||||
357 | * When the document was opened successfully, it will emit mimeTypeChanged() with the correct mimetype. | ||||
358 | * Otherwise, it will emit mimeTypeChanged() with one of the incorrect mimetypes. | ||||
359 | * | ||||
360 | * If the document was opened successfully, it will set up all the document specific stuff, like all the actions. | ||||
361 | * If the document or the given command line options request to e. g. open the print dialog, it will also do that. | ||||
362 | * | ||||
363 | * This function is called by ReadOnlyPart::openUrl(). | ||||
364 | * | ||||
365 | * @return Whether the document was opened successfully. | ||||
366 | */ | ||||
185 | bool openFile() override; | 367 | bool openFile() override; | ||
368 | | ||||
369 | /** | ||||
370 | * Makes openUrl(url, swapBacking = false) accessible as protected, overrides ReadOnlyPart::openUrl(). | ||||
371 | */ | ||||
186 | bool openUrl(const QUrl &url) override; | 372 | bool openUrl(const QUrl &url) override; | ||
187 | void guiActivateEvent(KParts::GUIActivateEvent *event) override; | 373 | void guiActivateEvent(KParts::GUIActivateEvent *event) override; | ||
374 | | ||||
375 | /** | ||||
376 | * Shows an animated message widget above the view area. | ||||
377 | * Error messages are even shown if Okular::Settings::showOSD is false. | ||||
378 | */ | ||||
188 | void displayInfoMessage( const QString &message, KMessageWidget::MessageType messageType = KMessageWidget::Information, int duration = -1 ); | 379 | void displayInfoMessage( const QString &message, KMessageWidget::MessageType messageType = KMessageWidget::Information, int duration = -1 ); | ||
380 | | ||||
189 | public: | 381 | public: | ||
382 | /** | ||||
383 | * If the user did changes to the file, will show a dialog asking whether to save or discard them. | ||||
384 | * | ||||
385 | * If the user choses to save them, saveFile() is called. | ||||
386 | * | ||||
387 | * Does not close the document. | ||||
388 | * | ||||
389 | * @return Whether all changes are saved or the unsaved changes may be discarded. | ||||
390 | */ | ||||
190 | bool queryClose() override; | 391 | bool queryClose() override; | ||
392 | | ||||
393 | /** | ||||
394 | * Overloads closeUrl(promptToSave = true). | ||||
395 | */ | ||||
191 | bool closeUrl() override; | 396 | bool closeUrl() override; | ||
397 | | ||||
398 | /** | ||||
399 | * Will close the currently opened document, and, if applicable, offer to save changes. | ||||
400 | * | ||||
401 | * After closing, this will cleanup by disabling actions, removing temporary files, etc. | ||||
402 | * | ||||
403 | * If this is called through openUrl(const QUrl&, bool swapInsteadOfOpening = true), this will do nothing. | ||||
404 | * | ||||
405 | * @param promptToSave If true, and the user made changes to the file, will ask whether to save before closing. | ||||
406 | * | ||||
407 | * @return Whether the document was closed. | ||||
408 | */ | ||||
192 | bool closeUrl(bool promptToSave) override; | 409 | bool closeUrl(bool promptToSave) override; | ||
193 | void setReadWrite(bool readwrite) override; | 410 | void setReadWrite(bool readwrite) override; | ||
194 | bool saveAs(const QUrl & saveUrl) override; | 411 | bool saveAs(const QUrl & saveUrl) override; | ||
195 | 412 | | |||
196 | protected Q_SLOTS: | 413 | protected Q_SLOTS: | ||
197 | // connected to actions | 414 | // connected to actions | ||
415 | | ||||
416 | /** | ||||
417 | * Opens an URL in this Part. Closes any currently opened document. | ||||
418 | * Use this to handle links which are embedded in documents. | ||||
419 | * Will use BrowserExtension interface to notify the parent application about the URL change. | ||||
420 | */ | ||||
What does this mean? Are these the functions which are called when the user clicks an action, and they will call the bunch of other open*(url) functions? davidhurka: What does this mean? Are these the functions which are called when the user clicks an action… | |||||
Already understand that they will call the bunch of other open*(url) functions, see Okular::Part Detailed Description. But I don’t see how they are connected to QActions, so I suggest to remove that line or clarify that these AreaToClick (ObjectRect) things in the Document are meant. davidhurka: Already understand that they will call the bunch of other open*(url) functions, see Okular… | |||||
198 | void openUrlFromDocument(const QUrl &url); | 421 | void openUrlFromDocument(const QUrl &url); | ||
422 | | ||||
423 | /** | ||||
424 | * Opens @p url, and goes to page N if given as URL fragment in the format #N. | ||||
425 | * If the document is already opened, goes directly to page N, without reopening the document. | ||||
426 | * | ||||
427 | * This is used to visit bookmarks. | ||||
428 | */ | ||||
199 | void openUrlFromBookmarks(const QUrl &url); | 429 | void openUrlFromBookmarks(const QUrl &url); | ||
430 | | ||||
Does this make sense? The parent application will loose control about the URL change. (Tried with KDevelop.) davidhurka: Does this make sense? The parent application will loose control about the URL change. (Tried… | |||||
Actually calls openUrl(), which informs the parent application. KDevelop just ignores that. Need to look how exactly that is done. davidhurka: Actually calls openUrl(), which informs the parent application. KDevelop just ignores that. | |||||
431 | /** | ||||
432 | * Opens the first URL in @p urls if used as embedded viewer, | ||||
433 | * or if the native shell is not set up to open documents in new tabs. | ||||
434 | * | ||||
435 | * Otherwise emits urlsDropped() with @p urls as argument. | ||||
436 | * | ||||
437 | * This is used to handle URLs which were dropped on the viewer widget. | ||||
438 | * | ||||
439 | * Will use BrowserExtension interface to notify the parent application about the URL change. | ||||
440 | */ | ||||
200 | void handleDroppedUrls( const QList<QUrl>& urls ); | 441 | void handleDroppedUrls( const QList<QUrl>& urls ); | ||
442 | | ||||
443 | /** | ||||
444 | * Shows the Go to Page dialog. | ||||
445 | */ | ||||
201 | void slotGoToPage(); | 446 | void slotGoToPage(); | ||
447 | | ||||
448 | /** | ||||
449 | * Goes back in the viewport history. | ||||
450 | */ | ||||
202 | void slotHistoryBack(); | 451 | void slotHistoryBack(); | ||
452 | | ||||
453 | /** | ||||
454 | * Goes forward in the viewport history. | ||||
455 | */ | ||||
203 | void slotHistoryNext(); | 456 | void slotHistoryNext(); | ||
457 | | ||||
458 | /** | ||||
459 | * Adds or removes a bookmark for the current viewport. | ||||
460 | * If the current viewport is already bookmarked, the bookmark is removed. | ||||
461 | * Otherwise, a new bookmark is added. | ||||
462 | */ | ||||
204 | void slotAddBookmark(); | 463 | void slotAddBookmark(); | ||
464 | | ||||
465 | /** | ||||
466 | * Opens a dialog to rename the bookmark. | ||||
467 | * | ||||
468 | * This slot must only be triggered by actions, which hold a viewport as data. | ||||
These slots use QObject::sender() and cast it to QAction* to extract the data, to convert it to a string and then to a DocumentViewport. davidhurka: These slots use QObject::sender() and cast it to QAction* to extract the data, to convert it to… | |||||
davidhurka: Will accept and ignore that for now. | |||||
469 | * The bookmark is determined using this data. | ||||
470 | */ | ||||
205 | void slotRenameBookmarkFromMenu(); | 471 | void slotRenameBookmarkFromMenu(); | ||
472 | | ||||
473 | /** | ||||
474 | * Removes the bookmark. | ||||
475 | * | ||||
476 | * This slot must only be triggered by actions, which hold a viewport as data. | ||||
477 | * The bookmark is determined using this data. | ||||
478 | */ | ||||
206 | void slotRemoveBookmarkFromMenu(); | 479 | void slotRemoveBookmarkFromMenu(); | ||
480 | | ||||
481 | /** | ||||
482 | * Shows a dialog to rename the bookmark of the current viewport. | ||||
483 | */ | ||||
207 | void slotRenameCurrentViewportBookmark(); | 484 | void slotRenameCurrentViewportBookmark(); | ||
485 | | ||||
486 | /** | ||||
487 | * Moves the viewport to the previous bookmark for this document. | ||||
488 | * The previous bookmark is searched from the current viewport on, without cycling. | ||||
489 | */ | ||||
208 | void slotPreviousBookmark(); | 490 | void slotPreviousBookmark(); | ||
491 | | ||||
492 | /** | ||||
493 | * Moves the viewport to the next bookmark for this document. | ||||
494 | * The next bookmark is searched from the current viewport on, without cycling. | ||||
495 | */ | ||||
209 | void slotNextBookmark(); | 496 | void slotNextBookmark(); | ||
497 | | ||||
498 | /** | ||||
499 | * Shows the incremental find bar and searches for the next occurrence of the current search pattern. | ||||
500 | */ | ||||
210 | void slotFindNext(); | 501 | void slotFindNext(); | ||
502 | | ||||
503 | /** | ||||
504 | * Shows the incremental find bar and searches backwards for the next occurrence of the current search pattern. | ||||
505 | */ | ||||
211 | void slotFindPrev(); | 506 | void slotFindPrev(); | ||
507 | | ||||
508 | /** | ||||
509 | * Shows the Save As dialog to save the current document. | ||||
510 | * The user can choose whether to save in the original format or as Okular archive. | ||||
511 | * In some embedding modes, does nothing and simply returns false. | ||||
512 | * | ||||
513 | * @return Whether the file was saved successfully. | ||||
514 | */ | ||||
212 | bool slotSaveFileAs(bool showOkularArchiveAsDefaultFormat = false); | 515 | bool slotSaveFileAs(bool showOkularArchiveAsDefaultFormat = false); | ||
516 | | ||||
517 | /** | ||||
518 | * Show a KNewStuff dialog to get books from the internet. | ||||
519 | * | ||||
520 | * @note | ||||
521 | * Not implemented anymore, does nothing. | ||||
522 | */ | ||||
213 | void slotGetNewStuff(); | 523 | void slotGetNewStuff(); | ||
524 | | ||||
525 | /** | ||||
526 | * Reparses the configuration. | ||||
527 | * Called when the KCoreConfigSkeleton changes. | ||||
528 | */ | ||||
214 | void slotNewConfig(); | 529 | void slotNewConfig(); | ||
530 | | ||||
531 | /** | ||||
532 | * This will open a popup menu, ideally on the view area. | ||||
533 | * This is intended as general purpose context menu for a particular page. | ||||
534 | * | ||||
535 | * @param page The page which shall be subject of the popup menu | ||||
536 | * @param point Where the menu will be shown, i. e. the cursor position | ||||
537 | * | ||||
538 | * @see showMenu() | ||||
539 | */ | ||||
215 | void slotShowMenu(const Okular::Page *page, const QPoint &point); | 540 | void slotShowMenu(const Okular::Page *page, const QPoint &point); | ||
541 | | ||||
542 | /** | ||||
543 | * This will open a popup menu, ideally on the Contents side panel. | ||||
544 | * This is intended as general purpose context menu for a TOC item. | ||||
545 | * See showMenu() for the menu structure. | ||||
546 | * | ||||
547 | * @param vp The viewport which the TOC item would open, used for bookmark actions. | ||||
548 | * @param point Where the menu will be shown, i. e. the cursor position. | ||||
549 | * @param title The title of the TOC item, used for Add Bookmark action. | ||||
550 | * | ||||
551 | * @see showMenu() | ||||
552 | */ | ||||
216 | void slotShowTOCMenu(const Okular::DocumentViewport &vp, const QPoint &point, const QString &title); | 553 | void slotShowTOCMenu(const Okular::DocumentViewport &vp, const QPoint &point, const QString &title); | ||
554 | | ||||
555 | /** | ||||
556 | * Will show the Properties dialog for the current document. | ||||
557 | * This dialog presents information like author, title, file path and size, ... and the fonts used in the document. | ||||
558 | */ | ||||
217 | void slotShowProperties(); | 559 | void slotShowProperties(); | ||
560 | | ||||
561 | /** | ||||
562 | * Will show the Embedded Files dialog for the current document. | ||||
563 | * This document provides access to files which are embedded in the document. | ||||
564 | * Embedding files is done e. g. with PDF documents. | ||||
565 | */ | ||||
218 | void slotShowEmbeddedFiles(); | 566 | void slotShowEmbeddedFiles(); | ||
567 | | ||||
568 | /** | ||||
569 | * Triggered by the Show Navigation Panel action. | ||||
570 | */ | ||||
219 | void slotShowLeftPanel(); | 571 | void slotShowLeftPanel(); | ||
572 | | ||||
573 | /** | ||||
574 | * Triggered by the Show Page Bar action. | ||||
575 | */ | ||||
220 | void slotShowBottomBar(); | 576 | void slotShowBottomBar(); | ||
577 | | ||||
578 | /** | ||||
579 | * Will enter the Presentation mode. | ||||
580 | * Creates the presentation widget if necessary, and shows it. | ||||
581 | */ | ||||
221 | void slotShowPresentation(); | 582 | void slotShowPresentation(); | ||
583 | | ||||
584 | /** | ||||
585 | * Will leave the Presentation mode. | ||||
586 | * Deletes the presentation widget, which was created by slotShowPresentation(). | ||||
587 | */ | ||||
222 | void slotHidePresentation(); | 588 | void slotHidePresentation(); | ||
223 | void slotExportAs(QAction *); | 589 | | ||
590 | /** | ||||
591 | * Exports the current document. Shows a dialog to get the output file name. | ||||
592 | * | ||||
593 | * @param action An action in the Export As menu, the position indicates the output format. | ||||
594 | */ | ||||
595 | void slotExportAs(QAction * action); | ||||
596 | | ||||
597 | /** | ||||
598 | * Will asynchronously convert a PS file to a PDF file, and open the PDF file when completed. | ||||
599 | * | ||||
600 | * Shows a dialog to get the path to the PS file. | ||||
601 | */ | ||||
224 | bool slotImportPSFile(); | 602 | bool slotImportPSFile(); | ||
603 | | ||||
604 | /** | ||||
605 | * Will show the About Backend dialog with information about the Generator used for the current document. | ||||
606 | */ | ||||
225 | void slotAboutBackend(); | 607 | void slotAboutBackend(); | ||
608 | | ||||
609 | /** | ||||
610 | * Triggered by the Reload action. | ||||
611 | * | ||||
612 | * @see slotAttemptReload() | ||||
613 | */ | ||||
226 | void slotReload(); | 614 | void slotReload(); | ||
615 | | ||||
616 | /** | ||||
617 | * Closes the document if this Part is used in the native Okular shell, otherwise shows a message box. | ||||
618 | * | ||||
619 | * Triggered when the document itself wants to be closed, i. e. the user clicked a document close link. | ||||
620 | */ | ||||
227 | void close(); | 621 | void close(); | ||
622 | | ||||
623 | /** | ||||
624 | * Shows a message box to explain that the application can not be quit from within the document. | ||||
625 | * | ||||
626 | * If this Part is embedded in a parent application without slotQuit(), application quit requests | ||||
627 | * of the document will be connected to this slot. | ||||
628 | */ | ||||
228 | void cannotQuit(); | 629 | void cannotQuit(); | ||
630 | | ||||
631 | /** | ||||
632 | * Shows the incremental find bar, selects everything in the search pattern line edit, and focuses it. | ||||
633 | */ | ||||
229 | void slotShowFindBar(); | 634 | void slotShowFindBar(); | ||
635 | | ||||
636 | /** | ||||
637 | * Maybe hides the incremental find bar. | ||||
Sounds funny, but that is how it works... davidhurka: Sounds funny, but that is how it works...
Even calls FindBar::maybeHide(). ;) | |||||
638 | * Find bar is not hidden if a search is ongoing. | ||||
639 | */ | ||||
230 | void slotHideFindBar(); | 640 | void slotHideFindBar(); | ||
641 | | ||||
642 | // TODO These three slots are connected to some KIO::Job stuff of ReadOnlyPart. | ||||
231 | void slotJobStarted(KIO::Job *job); | 643 | void slotJobStarted(KIO::Job *job); | ||
232 | void slotJobFinished(KJob *job); | 644 | void slotJobFinished(KJob *job); | ||
233 | void loadCancelled(const QString &reason); | 645 | void loadCancelled(const QString &reason); | ||
646 | | ||||
647 | /** | ||||
648 | * Gets an appropiate title from the document and emits setWindowCaption( QString ), | ||||
649 | * to set the window title. | ||||
650 | */ | ||||
234 | void setWindowTitleFromDocument(); | 651 | void setWindowTitleFromDocument(); | ||
235 | // can be connected to widget elements | 652 | | ||
653 | /** | ||||
Not really an idea what this means. And to which members does it belong? davidhurka: Not really an idea what this means. And to which members does it belong? | |||||
Belongs to updateViewActions() and enableTOC(bool). Connecting to widgets is not done and makes little sense, so I will remove that line. davidhurka: Belongs to updateViewActions() and enableTOC(bool). Connecting to widgets is not done and makes… | |||||
654 | * Enables or disables view actions according to the state of the currently loaded document. | ||||
655 | * View actions include actions that change the viewport, Reload, Copy, and selection actions. | ||||
656 | * Bookmark actions are also updated. | ||||
657 | */ | ||||
236 | void updateViewActions(); | 658 | void updateViewActions(); | ||
659 | | ||||
660 | /** | ||||
661 | * Updates bookmark actions according to the current document and viewport. | ||||
662 | */ | ||||
237 | void updateBookmarksActions(); | 663 | void updateBookmarksActions(); | ||
664 | | ||||
665 | /** | ||||
666 | * Enables or disables the Contents section in the sidebar. | ||||
667 | */ | ||||
238 | void enableTOC(bool enable); | 668 | void enableTOC(bool enable); | ||
669 | | ||||
670 | /** | ||||
671 | * Updates the Bookmarks actions, and updates the action list bookmarks_currentdocument. | ||||
672 | * This way, the Bookmarks menu in the menubar represents a list of all bookmarks in the current document. | ||||
673 | */ | ||||
239 | void slotRebuildBookmarkMenu(); | 674 | void slotRebuildBookmarkMenu(); | ||
675 | | ||||
676 | /** | ||||
677 | * Enables or disables the Layers section in the sidebar. | ||||
678 | */ | ||||
240 | void enableLayers( bool enable ); | 679 | void enableLayers( bool enable ); | ||
680 | | ||||
681 | /** | ||||
682 | * Enables or disables the Signatures section in the sidebar. | ||||
683 | */ | ||||
241 | void showSidebarSignaturesItem( bool show ); | 684 | void showSidebarSignaturesItem( bool show ); | ||
242 | 685 | | |||
243 | public Q_SLOTS: | 686 | public Q_SLOTS: | ||
244 | bool saveFile() override; | 687 | bool saveFile() override; | ||
245 | // connected to Shell action (and browserExtension), not local one | 688 | // connected to Shell action (and browserExtension), not local one | ||
689 | | ||||
690 | /** | ||||
691 | * Will show the Print dialog to print the current document. | ||||
692 | * | ||||
693 | * The print dialog is a QPrintDialog, with these options enabled (if applicable): | ||||
694 | * - Print to File, if supported by the Generator. | ||||
695 | * - Current Page, to print the currently shown page. | ||||
696 | * - Selection, to print pages which have bookmarks. | ||||
697 | * and these tabs added: | ||||
698 | * - Print Options (to choose the scale mode) | ||||
699 | * | ||||
700 | * If enableExitAfterPrint() was called, the viewer (i. e. this Part) will exit | ||||
701 | * after printing or when the print dialog is closed. | ||||
702 | * | ||||
703 | * Algorithm: | ||||
704 | * Configures a QPrinter using a QPrintDialog, and passes that to doPrint(). | ||||
705 | */ | ||||
246 | void slotPrint(); | 706 | void slotPrint(); | ||
247 | void slotFileDirty( const QString& ); | 707 | void slotFileDirty( const QString& ); | ||
708 | | ||||
709 | /** | ||||
710 | * Will try to reload the document. | ||||
711 | * | ||||
712 | * After reloading, will restore the previous state of the user interface. | ||||
713 | * | ||||
714 | * @param oneShot If false, and reloading failed, will start watching the file, so it will be reloaded when it changes the next time. | ||||
715 | * @param newUrl If set, the document will be reloaded from this URL instead of the original one. | ||||
716 | * | ||||
717 | * @return Whether the reload was successfull. If false, the document may still be reloaded later, because of watching. | ||||
718 | */ | ||||
248 | bool slotAttemptReload( bool oneShot = false, const QUrl &newUrl = QUrl() ); | 719 | bool slotAttemptReload( bool oneShot = false, const QUrl &newUrl = QUrl() ); | ||
720 | | ||||
721 | /** | ||||
722 | * Triggered by slotImportPSFile() trough QProcess::finished(), | ||||
723 | * when a PS file was converted to a PDF file. | ||||
724 | * | ||||
725 | * Opens the resulting PDF file. | ||||
726 | */ | ||||
249 | void psTransformEnded(int, QProcess::ExitStatus); | 727 | void psTransformEnded(int, QProcess::ExitStatus); | ||
728 | | ||||
729 | /** | ||||
730 | * Opens the generators configuration dialog (i. e. not the viewer configuration dialog). | ||||
731 | */ | ||||
250 | KConfigDialog * slotGeneratorPreferences(); | 732 | KConfigDialog * slotGeneratorPreferences(); | ||
251 | 733 | | |||
252 | void errorMessage( const QString &message, int duration = 0 ); | 734 | /** | ||
735 | * Shows an animated message above the view, even if OSD messages are disabled. | ||||
736 | * | ||||
737 | * @param message The text to show in the message. | ||||
738 | * @param duration The display duration in milliseconds, -1 to choose automatically. | ||||
739 | */ | ||||
740 | void errorMessage( const QString &message, int duration ); | ||||
741 | | ||||
742 | /** | ||||
743 | * Shows an animated message above the view, if OSD messages are enabled. | ||||
744 | * | ||||
745 | * @param message The text to show in the message. | ||||
746 | * @param duration The display duration in milliseconds, -1 to choose automatically. | ||||
747 | */ | ||||
A duration of 0 milliseconds seems a bit short to me. Why is this default? davidhurka: A duration of 0 milliseconds seems a bit short to me. Why is this default? | |||||
It's a silly default, the nice thing is that it's never the default since this is conneected from document::error and that one requires for a value for duration, so this = 0 can be just removed without any issue. aacid: It's a silly default, the nice thing is that it's never the default since this is conneected… | |||||
253 | void warningMessage( const QString &message, int duration = -1 ); | 748 | void warningMessage( const QString &message, int duration = -1 ); | ||
749 | | ||||
750 | /** | ||||
751 | * Shows an unintrusive, small message in the top of the view, if OSD messages are enabled. | ||||
752 | * | ||||
753 | * @param message The text to show in the message. | ||||
754 | * @param duration The display duration in milliseconds, -1 to choose automatically. | ||||
755 | */ | ||||
254 | void noticeMessage( const QString &message, int duration = -1 ); | 756 | void noticeMessage( const QString &message, int duration = -1 ); | ||
255 | 757 | | |||
758 | /** | ||||
759 | * Sets the size of the side panels at the left. | ||||
760 | * | ||||
761 | * @see slotShowLeftPanel() | ||||
762 | */ | ||||
256 | void moveSplitter( const int sideWidgetSize ); | 763 | void moveSplitter( const int sideWidgetSize ); | ||
257 | 764 | | |||
258 | private: | 765 | private: | ||
766 | /** | ||||
767 | * Populates a QMenu with actions to modify a bookmark. | ||||
768 | * | ||||
769 | * @param action The KBookmarkAction pointing to the bookmark. | ||||
770 | * @param[out] contextMenu The menu to which the actions will be added. | ||||
771 | * | ||||
772 | * @return False, if bookmark could not be found. | ||||
773 | */ | ||||
259 | bool aboutToShowContextMenu(QMenu *menu, QAction *action, QMenu *contextMenu); | 774 | bool aboutToShowContextMenu(QMenu *menu, QAction *action, QMenu *contextMenu); | ||
775 | | ||||
776 | /** | ||||
777 | * This opens a popup menu with various actions. | ||||
778 | * Use this to show the intended context menu for the view area or the Contents side panel. | ||||
779 | * | ||||
780 | * If @p page is not nullptr, there will be a section with title "Page N", | ||||
781 | * where N is the page number of @p page. It will contain bookmark and view actions specific to that page. | ||||
One view action is “Fit Width”. Unlike Fit Width from the menu bar, this Fit Width will not only set the zoom to Fit Width, but also set the view mode to Single Page, and center the viewport on page N. davidhurka: One view action is “Fit Width”. Unlike Fit Width from the menu bar, this Fit Width will not… | |||||
aacid: Yes, because this is "fit page N to width" | |||||
davidhurka: If that is intended, ok. | |||||
782 | * | ||||
783 | * In some cases it will contain a Tools section with some View actions | ||||
784 | * (currently from the Settings menu, see bug 163493). | ||||
785 | * | ||||
786 | * It is possible that no menu is shown, if none of its actions apply. | ||||
787 | * | ||||
788 | * The action Add Bookmark will add a bookmark which points to some viewport. | ||||
789 | * Tt will use the given viewport @p vp, if @p bookmarkTitle is also given. | ||||
790 | * Otherwise, it will use the current viewport, if @p page is the currently shown page. | ||||
791 | * Otherwise, it will use @p page as viewport. | ||||
792 | * | ||||
793 | * @param page The page which will be used for the section title, can be bookmarked by Add Bookmark. | ||||
794 | * @param point Where the popup menu will be opened, i. e. the curser position. | ||||
795 | * @param bookmarkTitle Will be used if the menu contains Add Bookmark. | ||||
796 | * @param vp The viewport which shall be used by bookmark actions. | ||||
797 | * @param showTOCActions Whether to add actions which affect the Contents side panel. | ||||
798 | */ | ||||
This is a function, but sounds like a signal. How about “addBookmarkActions”? davidhurka: This is a function, but sounds like a signal. How about “addBookmarkActions”? | |||||
aacid: good point, it's a pretty terrible name | |||||
260 | void showMenu(const Okular::Page *page, const QPoint &point, const QString &bookmarkTitle = QString(), const Okular::DocumentViewport &vp = DocumentViewport(), bool showTOCActions = false); | 799 | void showMenu(const Okular::Page *page, const QPoint &point, const QString &bookmarkTitle = QString(), const Okular::DocumentViewport &vp = DocumentViewport(), bool showTOCActions = false); | ||
800 | | ||||
261 | bool eventFilter(QObject * watched, QEvent * event) override; | 801 | bool eventFilter(QObject * watched, QEvent * event) override; | ||
This opens a context menu for context menu items, or what? It accepts events of type ContextMenu, that’s clear. To open the context menu, it seems to need a QMenu as event source. davidhurka: This opens a context menu for context menu items, or what?
It accepts events of type… | |||||
Seems like it opens a context menu for bookmark entries in the Bookmarks menu, to rename or delete a single bookmark. But such a menu does not open in my Okular. davidhurka: Seems like it opens a context menu for bookmark entries in the Bookmarks menu, to rename or… | |||||
aacid: It's an event filter, this is a basic way of filtering events in Qt.
Are you looking at the… | |||||
Doesn’t work here. Other popup menus can open a context menu for action collection actions, but didn’t notice that in a menubar menu so far. So it opens a context menu for a menubar menu, almost guessed. davidhurka: Doesn’t work here. Other popup menus can open a context menu for action collection actions, but… | |||||
262 | Document::OpenResult doOpenFile(const QMimeType &mime, const QString &fileNameToOpen, bool *isCompressedFile); | 802 | | ||
803 | /** | ||||
804 | * Tries to open a file. | ||||
Uh-oh, this is complicated. Would someone look over it? Yes, the language is not final. davidhurka: Uh-oh, this is complicated. Would someone look over it?
Yes, the language is not final. | |||||
davidhurka: Should be OK now, also improved language. | |||||
805 | * | ||||
806 | * If openUrl(QUrl &url, bool swapInsteadOfOpening) was called with swapInsteadOfOpening = true, | ||||
807 | * the backing file of the Generator will be changed, whitout interrupting the view. | ||||
808 | * | ||||
809 | * If a password is needed to open the document, it will try to fetch the password from the wallet or the user. | ||||
810 | * After successfully opening a document with password, the user can choose to store the password in the wallet. | ||||
811 | * | ||||
812 | * If the file is opened successfully, m_fileLastModified is set to the current time, | ||||
813 | * to allow watching the file for changes. | ||||
814 | * | ||||
815 | * Swapping the backing file is not possible with encrypted files. | ||||
816 | * | ||||
817 | * @param mime The mimetype of the file to open. If incorrect, opening will fail. | ||||
818 | * @param fileNameToOpen Path to a local file, which will be opened. | ||||
819 | * @param[out] out_isCompressedFile Whether the file was compressed and needed to be decompressed to a temporary file. | ||||
820 | * | ||||
821 | * @return Document::OpenSuccess or Document::OpenError. If the password could not be found, or it was intended to swap the backing file which needs a password, returns Document::OpenNeedsPassword. | ||||
822 | */ | ||||
823 | Document::OpenResult doOpenFile(const QMimeType &mime, const QString &fileNameToOpen, bool *out_isCompressedFile); | ||||
824 | | ||||
825 | /** | ||||
826 | * Opens a document from @p url, or swaps the backing file if @p swapInsteadOfOpening is set. | ||||
827 | * | ||||
828 | * Will interpret the URL fragment as page number or named destination, and open the document at an appropiate position. | ||||
829 | * | ||||
830 | * To do the actual opening, this calls KParts::ReadWritePart::openUrl( url ), which will call doOpenFile(). | ||||
831 | * | ||||
832 | * @param url Path to the new document file. | ||||
833 | * @param swapInsteadOfOpening If true, the current document is not closed, | ||||
834 | * but the generator will use the new file from now on. Useful to reload the document. | ||||
835 | * | ||||
836 | * @return Whether the document was opened successfully. | ||||
837 | */ | ||||
263 | bool openUrl( const QUrl &url, bool swapInsteadOfOpening ); | 838 | bool openUrl( const QUrl &url, bool swapInsteadOfOpening ); | ||
264 | 839 | | |||
265 | void setupViewerActions(); | 840 | void setupViewerActions(); | ||
266 | void setViewerShortcuts(); | 841 | void setViewerShortcuts(); | ||
267 | void setupActions(); | 842 | void setupActions(); | ||
268 | 843 | | |||
844 | /** | ||||
845 | * Sets orientation and document title of @p printer to match the current document as good as possible. | ||||
846 | */ | ||||
269 | void setupPrint( QPrinter &printer ); | 847 | void setupPrint( QPrinter &printer ); | ||
848 | | ||||
849 | /** | ||||
850 | * Prints the document to the given @p printer, assuming it is fully configured. | ||||
851 | */ | ||||
270 | bool doPrint( QPrinter &printer ); | 852 | bool doPrint( QPrinter &printer ); | ||
853 | | ||||
854 | /** | ||||
855 | * Opens a temporary file and tries to decompress the file @p path points to. | ||||
856 | * | ||||
857 | * @param[out] destpath Path to the created temporary file (only at success) | ||||
858 | * @param path Path to the compressed file to read from | ||||
859 | * @param compressionType Compression type of the compressed file. | ||||
860 | * | ||||
861 | * @return Whether the file was decompressed successfully. | ||||
862 | */ | ||||
271 | bool handleCompressed(QString &destpath, const QString &path, KCompressionDevice::CompressionType compressionType ); | 863 | bool handleCompressed(QString &destpath, const QString &path, KCompressionDevice::CompressionType compressionType ); | ||
272 | void rebuildBookmarkMenu( bool unplugActions = true ); | 864 | void rebuildBookmarkMenu( bool unplugActions = true ); | ||
273 | void updateAboutBackendAction(); | 865 | void updateAboutBackendAction(); | ||
274 | void unsetDummyMode(); | 866 | void unsetDummyMode(); | ||
275 | void slotRenameBookmark( const DocumentViewport &viewport ); | 867 | void slotRenameBookmark( const DocumentViewport &viewport ); | ||
276 | void slotRemoveBookmark( const DocumentViewport &viewport ); | 868 | void slotRemoveBookmark( const DocumentViewport &viewport ); | ||
277 | void resetStartArguments(); | 869 | void resetStartArguments(); | ||
278 | void checkNativeSaveDataLoss(bool *out_wontSaveForms, bool *out_wontSaveAnnotations) const; | 870 | void checkNativeSaveDataLoss(bool *out_wontSaveForms, bool *out_wontSaveAnnotations) const; | ||
Show All 26 Lines | 886 | #endif | |||
305 | bool m_documentOpenWithPassword; | 897 | bool m_documentOpenWithPassword; | ||
306 | bool m_swapInsteadOfOpening; // if set, the next open operation will replace the backing file (used when reloading just saved files) | 898 | bool m_swapInsteadOfOpening; // if set, the next open operation will replace the backing file (used when reloading just saved files) | ||
307 | 899 | | |||
308 | // main widgets | 900 | // main widgets | ||
309 | Sidebar *m_sidebar; | 901 | Sidebar *m_sidebar; | ||
310 | SearchWidget *m_searchWidget; | 902 | SearchWidget *m_searchWidget; | ||
311 | FindBar * m_findBar; | 903 | FindBar * m_findBar; | ||
312 | KMessageWidget * m_migrationMessage; | 904 | KMessageWidget * m_migrationMessage; | ||
313 | KMessageWidget * m_topMessage; | 905 | KMessageWidget * m_embeddedFilesMessage; | ||
314 | KMessageWidget * m_formsMessage; | 906 | KMessageWidget * m_formsMessage; | ||
315 | KMessageWidget * m_infoMessage; | 907 | KMessageWidget * m_infoMessage; | ||
316 | KMessageWidget * m_signatureMessage; | 908 | KMessageWidget * m_signatureMessage; | ||
317 | QPointer<ThumbnailList> m_thumbnailList; | 909 | QPointer<ThumbnailList> m_thumbnailList; | ||
318 | QPointer<PageView> m_pageView; | 910 | QPointer<PageView> m_pageView; | ||
319 | QPointer<TOC> m_toc; | 911 | QPointer<TOC> m_toc; | ||
320 | QPointer<MiniBarLogic> m_miniBarLogic; | 912 | QPointer<MiniBarLogic> m_miniBarLogic; | ||
321 | QPointer<MiniBar> m_miniBar; | 913 | QPointer<MiniBar> m_miniBar; | ||
▲ Show 20 Lines • Show All 100 Lines • ▼ Show 20 Line(s) | 1012 | private Q_SLOTS: | |||
422 | void slotHandleActivatedSourceReference(const QString& absFileName, int line, int col, bool *handled); | 1014 | void slotHandleActivatedSourceReference(const QString& absFileName, int line, int col, bool *handled); | ||
423 | }; | 1015 | }; | ||
424 | 1016 | | |||
425 | } | 1017 | } | ||
426 | 1018 | | |||
427 | #endif | 1019 | #endif | ||
428 | 1020 | | |||
429 | /* kate: replace-tabs on; indent-width 4; */ | 1021 | /* kate: replace-tabs on; indent-width 4; */ | ||
1022 | | ||||
1023 | post |
Do we really need to document a 1 line function?