1 /* 2 SPDX-FileCopyrightText: 2004-2005 Enrico Ros <eros.kde@email.it> 3 SPDX-FileCopyrightText: 2004-2008 Albert Astals Cid <aacid@kde.org> 4 5 Work sponsored by the LiMux project of the city of Munich: 6 SPDX-FileCopyrightText: 2017 Klarälvdalens Datakonsult AB a KDAB Group company <info@kdab.com> 7 8 SPDX-License-Identifier: GPL-2.0-or-later 9 */ 10 11 #ifndef _OKULAR_DOCUMENT_H_ 12 #define _OKULAR_DOCUMENT_H_ 13 14 #include "area.h" 15 #include "global.h" 16 #include "okularcore_export.h" 17 #include "pagesize.h" 18 19 #include <QDomDocument> 20 #include <QObject> 21 #include <QPrinter> 22 #include <QStringList> 23 #include <QVector> 24 25 #include <QMimeType> 26 #include <QUrl> 27 28 class KConfigDialog; 29 class KPluginMetaData; 30 class KXMLGUIClient; 31 class DocumentItem; 32 class QAbstractItemModel; 33 34 namespace Okular 35 { 36 class Annotation; 37 class BookmarkManager; 38 class CertificateStore; 39 class DocumentInfoPrivate; 40 class DocumentObserver; 41 class DocumentPrivate; 42 class DocumentSynopsis; 43 class DocumentViewport; 44 class EmbeddedFile; 45 class ExportFormat; 46 class FontInfo; 47 class FormField; 48 class FormFieldText; 49 class FormFieldButton; 50 class FormFieldChoice; 51 class Generator; 52 class Action; 53 class MovieAction; 54 class Page; 55 class PixmapRequest; 56 class RenditionAction; 57 class NewSignatureData; 58 struct NewSignatureDataPrivate; 59 class SourceReference; 60 class View; 61 class VisiblePageRect; 62 class SignatureInfo; 63 64 /** IDs for seaches. Globally defined here. **/ 65 #define PART_SEARCH_ID 1 66 #define PAGEVIEW_SEARCH_ID 2 67 #define SW_SEARCH_ID 3 68 #define PRESENTATION_SEARCH_ID 4 69 70 /** 71 * The DocumentInfo structure can be filled in by generators to display 72 * metadata about the currently opened file. 73 */ 74 class OKULARCORE_EXPORT DocumentInfo 75 { 76 friend class Document; 77 78 public: 79 /** 80 * The list of predefined keys. 81 */ 82 enum Key { 83 Title, ///< The title of the document 84 Subject, ///< The subject of the document 85 Description, ///< The description of the document 86 Author, ///< The author of the document 87 Creator, ///< The creator of the document (this can be different from the author) 88 Producer, ///< The producer of the document (e.g. some software) 89 Copyright, ///< The copyright of the document 90 Pages, ///< The number of pages of the document 91 CreationDate, ///< The date of creation of the document 92 ModificationDate, ///< The date of last modification of the document 93 MimeType, ///< The mime type of the document 94 Category, ///< The category of the document 95 Keywords, ///< The keywords which describe the content of the document 96 FilePath, ///< The path of the file @since 0.10 (KDE 4.4) 97 DocumentSize, ///< The size of the document @since 0.10 (KDE 4.4) 98 PagesSize, ///< The size of the pages (if all pages have the same size) @since 0.10 (KDE 4.4) 99 CustomKeys, ///< All the custom keys the generator supports @since 0.21 100 Invalid ///< An invalid key @since 0.21. It will always be the last element in the enum 101 }; 102 103 /** 104 * Creates a new document info. 105 */ 106 DocumentInfo(); 107 DocumentInfo(const DocumentInfo &info); 108 DocumentInfo &operator=(const DocumentInfo &); 109 110 ~DocumentInfo(); 111 112 /** 113 * Returns all the keys present in this DocumentInfo 114 * 115 * @since 0.21 116 */ 117 QStringList keys() const; 118 119 /** 120 * Returns the value for a given key or an null string when the 121 * key doesn't exist. 122 */ 123 QString get(Key key) const; 124 125 /** 126 * Returns the value for a given key or an null string when the 127 * key doesn't exist. 128 */ 129 QString get(const QString &key) const; 130 131 /** 132 * Sets a value for a custom key. The title should be an i18n'ed 133 * string, since it's used in the document information dialog. 134 */ 135 void set(const QString &key, const QString &value, const QString &title = QString()); 136 137 /** 138 * Sets a value for a special key. The title should be an i18n'ed 139 * string, since it's used in the document information dialog. 140 */ 141 void set(Key key, const QString &value); 142 143 /** 144 * Returns the user visible string for the given key 145 * Takes into account keys added by the set() that takes a QString 146 * 147 * @since 0.21 148 */ 149 QString getKeyTitle(const QString &key) const; 150 151 /** 152 * Returns the internal string for the given key 153 * @since 0.10 (KDE 4.4) 154 */ 155 static QString getKeyString(Key key); 156 157 /** 158 * Returns the user visible string for the given key 159 * @since 0.10 (KDE 4.4) 160 */ 161 static QString getKeyTitle(Key key); 162 163 /** 164 * Returns the Key from a string key 165 * @since 0.21 166 */ 167 static Key getKeyFromString(const QString &key); 168 169 private: 170 DocumentInfoPrivate *d; 171 }; 172 173 /** 174 * @short The Document. Heart of everything. Actions take place here. 175 * 176 * The Document is the main object in Okular. All views query the Document to 177 * get data/properties or even for accessing pages (in a 'const' way). 178 * 179 * It is designed to keep it detached from the document type (pdf, ps, you 180 * name it..) so whenever you want to get some data, it asks its internal 181 * generators to do the job and return results in a format-independent way. 182 * 183 * Apart from the generator (the currently running one) the document stores 184 * all the Pages ('Page' class) of the current document in a vector and 185 * notifies all the registered DocumentObservers when some content changes. 186 * 187 * For a better understanding of hierarchies @see README.internals.png 188 * @see DocumentObserver, Page 189 */ 190 class OKULARCORE_EXPORT Document : public QObject 191 { 192 Q_OBJECT 193 194 public: 195 /** 196 * Creates a new document with the given @p widget as widget to relay GUI things (messageboxes, ...). 197 */ 198 explicit Document(QWidget *widget); 199 200 /** 201 * Destroys the document. 202 */ 203 ~Document() override; 204 205 /** 206 * Describes the result of an open document operation. 207 * @since 0.20 (KDE 4.14) 208 */ 209 enum OpenResult { 210 OpenSuccess, //< The document was opened successfully 211 OpenError, //< The document failed to open 212 OpenNeedsPassword //< The document needs a password to be opened or the one provided is not the correct 213 }; 214 215 /** 216 * Opens the document. 217 * @since 0.20 (KDE 4.14) 218 */ 219 OpenResult openDocument(const QString &docFile, const QUrl &url, const QMimeType &mime, const QString &password = QString()); 220 221 /** 222 * Closes the document. 223 */ 224 void closeDocument(); 225 226 /** 227 * Registers a new @p observer for the document. 228 */ 229 void addObserver(DocumentObserver *observer); 230 231 /** 232 * Unregisters the given @p observer for the document. 233 */ 234 void removeObserver(DocumentObserver *observer); 235 236 /** 237 * Reparses and applies the configuration. 238 */ 239 void reparseConfig(); 240 241 /** 242 * Returns whether the document is currently opened. 243 */ 244 bool isOpened() const; 245 246 /** 247 * Returns the meta data of the document. 248 */ 249 DocumentInfo documentInfo() const; 250 251 /** 252 * Returns the asked set of meta data of the document. The result may contain more 253 * metadata than the one asked for. 254 */ 255 DocumentInfo documentInfo(const QSet<DocumentInfo::Key> &keys) const; 256 257 /** 258 * Returns the table of content of the document or 0 if no 259 * table of content is available. 260 */ 261 const DocumentSynopsis *documentSynopsis() const; 262 263 /** 264 * Starts the reading of the information about the fonts in the 265 * document, if available. 266 * 267 * The results as well the end of the reading is notified using the 268 * signals gotFont(), fontReadingProgress() and fontReadingEnded() 269 */ 270 void startFontReading(); 271 272 /** 273 * Force the termination of the reading of the information about the 274 * fonts in the document, if running. 275 */ 276 void stopFontReading(); 277 278 /** 279 * Whether the current document can provide information about the 280 * fonts used in it. 281 */ 282 bool canProvideFontInformation() const; 283 284 /** 285 * Whether the current document can perform digital signing. 286 */ 287 bool canSign() const; 288 289 /** 290 * Returns the list of embedded files or 0 if no embedded files 291 * are available. 292 */ 293 const QList<EmbeddedFile *> *embeddedFiles() const; 294 295 /** 296 * Returns the page object for the given page @p number or 0 297 * if the number is out of range. 298 */ 299 const Page *page(int number) const; 300 301 /** 302 * Returns the current viewport of the document. 303 */ 304 const DocumentViewport &viewport() const; 305 306 /** 307 * Sets the list of visible page rectangles. 308 * @see VisiblePageRect 309 */ 310 void setVisiblePageRects(const QVector<VisiblePageRect *> &visiblePageRects, DocumentObserver *excludeObserver = nullptr); 311 312 /** 313 * Returns the list of visible page rectangles. 314 */ 315 const QVector<VisiblePageRect *> &visiblePageRects() const; 316 317 /** 318 * Returns the number of the current page. 319 */ 320 uint currentPage() const; 321 322 /** 323 * Returns the number of pages of the document. 324 */ 325 uint pages() const; 326 327 /** 328 * Returns the url of the currently opened document. 329 */ 330 QUrl currentDocument() const; 331 332 /** 333 * Returns whether the given @p action is allowed in the document. 334 * @see @ref Permission 335 */ 336 bool isAllowed(Permission action) const; 337 338 /** 339 * Returns whether the document supports searching. 340 */ 341 bool supportsSearching() const; 342 343 /** 344 * Returns whether the document supports the listing of page sizes. 345 */ 346 bool supportsPageSizes() const; 347 348 /** 349 * Returns whether the current document supports tiles 350 * 351 * @since 0.16 (KDE 4.10) 352 */ 353 bool supportsTiles() const; 354 355 /** 356 * Returns the list of supported page sizes or an empty list if this 357 * feature is not available. 358 * @see supportsPageSizes() 359 */ 360 PageSize::List pageSizes() const; 361 362 /** 363 * Returns whether the document supports the export to ASCII text. 364 */ 365 bool canExportToText() const; 366 367 /** 368 * Exports the document as ASCII text and saves it under @p fileName. 369 */ 370 bool exportToText(const QString &fileName) const; 371 372 /** 373 * Returns the list of supported export formats. 374 * @see ExportFormat 375 */ 376 QList<ExportFormat> exportFormats() const; 377 378 /** 379 * Exports the document in the given @p format and saves it under @p fileName. 380 */ 381 bool exportTo(const QString &fileName, const ExportFormat &format) const; 382 383 /** 384 * Returns whether the document history is at the begin. 385 */ 386 bool historyAtBegin() const; 387 388 /** 389 * Returns whether the document history is at the end. 390 */ 391 bool historyAtEnd() const; 392 393 /** 394 * Returns the meta data for the given @p key and @p option or an empty variant 395 * if the key doesn't exists. 396 */ 397 QVariant metaData(const QString &key, const QVariant &option = QVariant()) const; 398 399 /** 400 * Returns the current rotation of the document. 401 */ 402 Rotation rotation() const; 403 404 /** 405 * If all pages have the same size this method returns it, if the page sizes 406 * differ an empty size object is returned. 407 */ 408 QSizeF allPagesSize() const; 409 410 /** 411 * Returns the size string for the given @p page or an empty string 412 * if the page is out of range. 413 */ 414 QString pageSizeString(int page) const; 415 416 /** 417 * Returns the gui client of the generator, if it provides one. 418 */ 419 KXMLGUIClient *guiClient(); 420 421 /** 422 * Sets the current document viewport to the given @p page. 423 * 424 * @param page The number of the page. 425 * @param excludeObserver The observer ids which shouldn't be effected by this change. 426 * @param smoothMove Whether the move shall be animated smoothly. 427 */ 428 void setViewportPage(int page, DocumentObserver *excludeObserver = nullptr, bool smoothMove = false); 429 430 /** 431 * Sets the current document viewport to the given @p viewport. 432 * 433 * @param viewport The document viewport. 434 * @param excludeObserver The observer which shouldn't be effected by this change. 435 * @param smoothMove Whether the move shall be animated smoothly. 436 */ 437 void setViewport(const DocumentViewport &viewport, DocumentObserver *excludeObserver = nullptr, bool smoothMove = false); 438 439 /** 440 * Sets the current document viewport to the given @p viewport. 441 * BCI TODO: merge with setViewport, adding a parameter "bool updateHistory = true" 442 * 443 * @param viewport The document viewport. 444 * @param excludeObserver The observer which shouldn't be effected by this change. 445 * @param smoothMove Whether the move shall be animated smoothly. 446 * @param updateHistory Whether to consider the change of viewport for the history navigation 447 */ 448 void setViewportWithHistory(const DocumentViewport &viewport, DocumentObserver *excludeObserver = nullptr, bool smoothMove = false, bool updateHistory = true); 449 450 /** 451 * Sets the current document viewport to the next viewport in the 452 * viewport history. 453 */ 454 void setPrevViewport(); 455 456 /** 457 * Sets the current document viewport to the previous viewport in the 458 * viewport history. 459 */ 460 void setNextViewport(); 461 462 /** 463 * Sets the next @p viewport in the viewport history. 464 */ 465 void setNextDocumentViewport(const DocumentViewport &viewport); 466 467 /** 468 * Sets the next @p namedDestination in the viewport history. 469 * 470 * @since 0.9 (KDE 4.3) 471 */ 472 void setNextDocumentDestination(const QString &namedDestination); 473 474 /** 475 * Sets the zoom for the current document. 476 */ 477 void setZoom(int factor, DocumentObserver *excludeObserver = nullptr); 478 479 /** 480 * Describes the possible options for the pixmap requests. 481 */ 482 enum PixmapRequestFlag { 483 NoOption = 0, ///< No options 484 RemoveAllPrevious = 1 ///< Remove all the previous requests, even for non requested page pixmaps 485 }; 486 Q_DECLARE_FLAGS(PixmapRequestFlags, PixmapRequestFlag) 487 488 /** 489 * Sends @p requests for pixmap generation. 490 * 491 * The same as requestPixmaps( requests, RemoveAllPrevious ); 492 */ 493 void requestPixmaps(const QLinkedList<PixmapRequest *> &requests); 494 495 /** 496 * Sends @p requests for pixmap generation. 497 * 498 * @param requests the linked list of requests 499 * @param reqOptions the options for the request 500 * 501 * @since 0.7 (KDE 4.1) 502 */ 503 void requestPixmaps(const QLinkedList<PixmapRequest *> &requests, PixmapRequestFlags reqOptions); 504 505 /** 506 * Sends a request for text page generation for the given page @p pageNumber. 507 */ 508 void requestTextPage(uint pageNumber); 509 510 /** 511 * Adds a new @p annotation to the given @p page. 512 */ 513 void addPageAnnotation(int page, Annotation *annotation); 514 515 /** 516 * Tests if the @p annotation can be modified 517 * 518 * @since 0.15 (KDE 4.9) 519 */ 520 bool canModifyPageAnnotation(const Annotation *annotation) const; 521 522 /** 523 * Prepares to modify the properties of the given @p annotation. 524 * Must be called before the annotation's properties are modified 525 * 526 * @since 0.17 (KDE 4.11) 527 */ 528 void prepareToModifyAnnotationProperties(Annotation *annotation); 529 530 /** 531 * Modifies the given @p annotation on the given @p page. 532 * Must be preceded by a call to prepareToModifyAnnotationProperties before 533 * the annotation's properties are modified 534 * 535 * @since 0.17 (KDE 4.11) 536 */ 537 void modifyPageAnnotationProperties(int page, Annotation *annotation); 538 539 /** 540 * Translates the position of the given @p annotation on the given @p page by a distance @p delta in normalized coordinates. 541 * 542 * Consecutive translations applied to the same @p annotation are merged together on the undo stack if the 543 * BeingMoved flag is set on the @p annotation. 544 * 545 * @since 0.17 (KDE 4.11) 546 */ 547 void translatePageAnnotation(int page, Annotation *annotation, const Okular::NormalizedPoint &delta); 548 549 /** 550 * Adjusts the position of the top-left and bottom-right corners of given @p annotation on the given @p page. 551 * 552 * Can be used to implement resize functionality. 553 * @p delta1 in normalized coordinates is added to top-left. 554 * @p delta2 in normalized coordinates is added to bottom-right. 555 * 556 * Consecutive adjustments applied to the same @p annotation are merged together on the undo stack if the 557 * BeingResized flag is set on the @p annotation. 558 * 559 * @since 1.1.0 560 */ 561 void adjustPageAnnotation(int page, Annotation *annotation, const Okular::NormalizedPoint &delta1, const Okular::NormalizedPoint &delta2); 562 563 /** 564 * Edits the plain text contents of the given @p annotation on the given @p page. 565 * 566 * The contents are set to @p newContents with cursor position @p newCursorPos. 567 * The previous cursor position @p prevCursorPos and previous anchor position @p prevAnchorPos 568 * must also be supplied so that they can be restored if the edit action is undone. 569 * 570 * The Annotation's internal contents should not be modified prior to calling this method. 571 * 572 * @since 0.17 (KDE 4.11) 573 */ 574 void editPageAnnotationContents(int page, Annotation *annotation, const QString &newContents, int newCursorPos, int prevCursorPos, int prevAnchorPos); 575 576 /** 577 * Tests if the @p annotation can be removed 578 * 579 * @since 0.15 (KDE 4.9) 580 */ 581 bool canRemovePageAnnotation(const Annotation *annotation) const; 582 583 /** 584 * Removes the given @p annotation from the given @p page. 585 */ 586 void removePageAnnotation(int page, Annotation *annotation); 587 588 /** 589 * Removes the given @p annotations from the given @p page. 590 */ 591 void removePageAnnotations(int page, const QList<Annotation *> &annotations); 592 593 /** 594 * Clears the text selection highlights for the given @p page, 595 * creates new ones if @p rect is not nullptr, 596 * and deletes @p rect. 597 * 598 * @param page The number of the page. 599 * @param rect The rectangle of the selection. 600 * @param color The color of the selection. 601 */ 602 void setPageTextSelection(int page, RegularAreaRect *rect, const QColor &color); 603 604 /** 605 * Returns true if there is an undo command available; otherwise returns false. 606 * @since 0.17 (KDE 4.11) 607 */ 608 bool canUndo() const; 609 610 /** 611 * Returns true if there is a redo command available; otherwise returns false. 612 * @since 0.17 (KDE 4.11) 613 */ 614 bool canRedo() const; 615 616 /** 617 * Describes the possible search types. 618 */ 619 enum SearchType { 620 NextMatch, ///< Search next match 621 PreviousMatch, ///< Search previous match 622 AllDocument, ///< Search complete document 623 GoogleAll, ///< Search complete document (all words in google style) 624 GoogleAny ///< Search complete document (any words in google style) 625 }; 626 627 /** 628 * Describes how search ended 629 */ 630 // TODO remove EndOfDocumentReached when we break API 631 enum SearchStatus { 632 MatchFound, ///< Any match was found 633 NoMatchFound, ///< No match was found 634 SearchCancelled, ///< The search was cancelled 635 EndOfDocumentReached ///< This is not ever emitted since 1.3. The end of document was reached without any match @since 0.20 (KDE 4.14) 636 }; 637 638 /** 639 * Searches the given @p text in the document. 640 * 641 * @param searchID The unique id for this search request. 642 * @param text The text to be searched. 643 * @param fromStart Whether the search should be started at begin of the document. 644 * @param caseSensitivity Whether the search is case sensitive. 645 * @param type The type of the search. @ref SearchType 646 * @param moveViewport Whether the viewport shall be moved to the position of the matches. 647 * @param color The highlighting color of the matches. 648 */ 649 void searchText(int searchID, const QString &text, bool fromStart, Qt::CaseSensitivity caseSensitivity, SearchType type, bool moveViewport, const QColor &color); 650 651 /** 652 * Continues the search for the given @p searchID. 653 */ 654 void continueSearch(int searchID); 655 656 /** 657 * Continues the search for the given @p searchID, optionally specifying 658 * a new type for the search. 659 * 660 * @since 0.7 (KDE 4.1) 661 */ 662 void continueSearch(int searchID, SearchType type); 663 664 /** 665 * Resets the search for the given @p searchID. 666 */ 667 void resetSearch(int searchID); 668 669 /** 670 * Returns the bookmark manager of the document. 671 */ 672 BookmarkManager *bookmarkManager() const; 673 674 /** 675 * Processes the given @p action. 676 */ 677 void processAction(const Action *action); 678 679 /** 680 * Processes the given format @p action on @p fft. 681 * 682 * @since 1.9 683 */ 684 void processFormatAction(const Action *action, Okular::FormFieldText *fft); 685 686 /** 687 * Processes the given keystroke @p action on @p fft. 688 * 689 * @since 1.9 690 */ 691 void processKeystrokeAction(const Action *action, Okular::FormFieldText *fft, bool &returnCode); 692 693 /** 694 * Processes the given focus action on the field. 695 * 696 * @since 1.9 697 */ 698 void processFocusAction(const Action *action, Okular::FormField *field); 699 700 /** 701 * Processes the given keystroke @p action on @p fft. 702 * 703 * @since 1.9 704 */ 705 void processValidateAction(const Action *action, Okular::FormFieldText *fft, bool &returnCode); 706 707 /** 708 * Returns a list of the bookmarked.pages 709 */ 710 QList<int> bookmarkedPageList() const; 711 712 /** 713 * Returns the range of the bookmarked.pages 714 */ 715 QString bookmarkedPageRange() const; 716 717 /** 718 * Processes/Executes the given source @p reference. 719 */ 720 void processSourceReference(const SourceReference *reference); 721 722 /** 723 * Returns whether the document can configure the printer itself. 724 */ 725 bool canConfigurePrinter() const; 726 727 /** 728 * What type of printing a document supports 729 */ 730 enum PrintingType { 731 NoPrinting, ///< Printing Not Supported 732 NativePrinting, ///< Native Cross-Platform Printing 733 PostscriptPrinting ///< Postscript file printing 734 }; 735 736 /** 737 * Returns what sort of printing the document supports: 738 * Native, Postscript, None 739 */ 740 PrintingType printingSupport() const; 741 742 /** 743 * Returns whether the document supports printing to both PDF and PS files. 744 */ 745 bool supportsPrintToFile() const; 746 747 /** 748 * Prints the document to the given @p printer. 749 */ 750 bool print(QPrinter &printer); 751 752 /** 753 * Returns the last print error in case print() failed 754 * @since 0.11 (KDE 4.5) 755 */ 756 QString printError() const; 757 758 /** 759 * Returns a custom printer configuration page or 0 if no 760 * custom printer configuration page is available. 761 * 762 * The returned object should be of a PrintOptionsWidget subclass 763 * (which is not officially enforced by the signature for binary 764 * compatibility reasons). 765 */ 766 QWidget *printConfigurationWidget() const; 767 768 /** 769 * Fill the KConfigDialog @p dialog with the setting pages of the 770 * generators. 771 */ 772 void fillConfigDialog(KConfigDialog *dialog); 773 774 /** 775 * Returns the number of generators that have a configuration widget. 776 */ 777 int configurableGenerators() const; 778 779 /** 780 * Returns the list with the supported MIME types. 781 */ 782 QStringList supportedMimeTypes() const; 783 784 /** 785 * Returns the metadata associated with the generator. May be invalid. 786 */ 787 KPluginMetaData generatorInfo() const; 788 789 /** 790 * Returns whether the generator supports hot-swapping the current file 791 * with another identical file 792 * 793 * @since 1.3 794 */ 795 bool canSwapBackingFile() const; 796 797 /** 798 * Reload the document from a new location, without any visible effect 799 * to the user. 800 * 801 * The new file must be identical to the current one or, if the document 802 * has been modified (eg the user edited forms and annotations), the new 803 * document must have these changes too. For example, you can call 804 * saveChanges first to write changes to a file and then swapBackingFile 805 * to switch to the new location. 806 * 807 * @since 1.3 808 */ 809 bool swapBackingFile(const QString &newFileName, const QUrl &url); 810 811 /** 812 * Same as swapBackingFile, but newFileName must be a .okular file. 813 * 814 * The new file must be identical to the current one or, if the document 815 * has been modified (eg the user edited forms and annotations), the new 816 * document must have these changes too. For example, you can call 817 * saveDocumentArchive first to write changes to a file and then 818 * swapBackingFileArchive to switch to the new location. 819 * 820 * @since 1.3 821 */ 822 bool swapBackingFileArchive(const QString &newFileName, const QUrl &url); 823 824 /** 825 * Sets the history to be clean 826 * 827 * @since 1.3 828 */ 829 void setHistoryClean(bool clean); 830 831 bool isHistoryClean() const; 832 833 /** 834 * Saving capabilities. Their availability varies according to the 835 * underlying generator and/or the document type. 836 * 837 * @see canSaveChanges (SaveCapability) 838 * @since 0.15 (KDE 4.9) 839 */ 840 enum SaveCapability { 841 SaveFormsCapability = 1, ///< Can save form changes 842 SaveAnnotationsCapability = 2 ///< Can save annotation changes 843 }; 844 845 /** 846 * Returns whether it's possible to save a given category of changes to 847 * another document. 848 * 849 * @since 0.15 (KDE 4.9) 850 */ 851 bool canSaveChanges(SaveCapability cap) const; 852 853 /** 854 * Returns whether the changes to the document (modified annotations, 855 * values in form fields, etc) can be saved to another document. 856 * 857 * Equivalent to the logical OR of canSaveChanges(SaveCapability) for 858 * each capability. 859 * 860 * @since 0.7 (KDE 4.1) 861 */ 862 bool canSaveChanges() const; 863 864 /** 865 * Save the document and the optional changes to it to the specified 866 * @p fileName. 867 * 868 * @since 0.7 (KDE 4.1) 869 */ 870 bool saveChanges(const QString &fileName); 871 872 /** 873 * Save the document and the optional changes to it to the specified 874 * @p fileName and returns a @p errorText if fails. 875 * 876 * @since 0.10 (KDE 4.4) 877 */ 878 bool saveChanges(const QString &fileName, QString *errorText); 879 880 /** 881 * Register the specified @p view for the current document. 882 * 883 * It is unregistered from the previous document, if any. 884 * 885 * @since 0.7 (KDE 4.1) 886 */ 887 void registerView(View *view); 888 889 /** 890 * Unregister the specified @p view from the current document. 891 * 892 * @since 0.7 (KDE 4.1) 893 */ 894 void unregisterView(View *view); 895 896 /** 897 * Gets the font data for the given font 898 * 899 * @since 0.8 (KDE 4.2) 900 */ 901 QByteArray fontData(const FontInfo &font) const; 902 903 /** 904 * Opens a document archive. 905 * 906 * @since 0.20 (KDE 4.14) 907 */ 908 OpenResult openDocumentArchive(const QString &docFile, const QUrl &url, const QString &password = QString()); 909 910 /** 911 * Saves a document archive. 912 * 913 * @since 0.8 (KDE 4.2) 914 */ 915 bool saveDocumentArchive(const QString &fileName); 916 917 /** 918 * Extract the document file from the current archive. 919 * 920 * @warning This function only works if the current file is a document archive 921 * 922 * @since 1.3 923 */ 924 bool extractArchivedFile(const QString &destFileName); 925 926 /** 927 * Asks the generator to dynamically generate a SourceReference for a given 928 * page number and absolute X and Y position on this page. 929 * 930 * @attention Ownership of the returned SourceReference is transferred to the caller. 931 * @note This method does not call processSourceReference( const SourceReference * ) 932 * 933 * @since 0.10 (KDE 4.4) 934 */ 935 const SourceReference *dynamicSourceReference(int pageNr, double absX, double absY); 936 937 /** 938 * Returns the orientation of the document (for printing purposes). This 939 * is used in the KPart to initialize the print dialog and in the 940 * generators to check whether the document needs to be rotated or not. 941 * 942 * @since 0.14 (KDE 4.8) 943 */ 944 QPrinter::Orientation orientation() const; 945 946 /** 947 * Control annotation editing (creation, modification and removal), 948 * which is enabled by default. 949 * 950 * @since 0.15 (KDE 4.9) 951 */ 952 void setAnnotationEditingEnabled(bool enable); 953 954 /** 955 * Returns which wallet data to use to read/write the password for the given fileName 956 * 957 * @since 0.20 (KDE 4.14) 958 */ 959 void walletDataForFile(const QString &fileName, QString *walletName, QString *walletFolder, QString *walletKey) const; 960 961 /** 962 * Since version 0.21, okular does not allow editing annotations and 963 * form data if they are stored in the docdata directory (like older 964 * okular versions did by default). 965 * If this flag is set, then annotations and forms cannot be edited. 966 * 967 * @since 1.3 968 */ 969 bool isDocdataMigrationNeeded() const; 970 971 /** 972 * Delete annotations and form data from the docdata folder. Call it if 973 * isDocdataMigrationNeeded() was true and you've just saved them to an 974 * external file. 975 * 976 * @since 1.3 977 */ 978 void docdataMigrationDone(); 979 980 /** 981 * Returns the model for rendering layers (NULL if the document has no layers) 982 * 983 * @since 0.24 984 */ 985 QAbstractItemModel *layersModel() const; 986 987 /** 988 * Returns the reason why the file opening failed, if any. 989 * 990 * @since 1.10 991 */ 992 QString openError() const; 993 994 /** 995 * Digitally sign document 996 * 997 * @since 21.04 998 */ 999 bool sign(const NewSignatureData &data, const QString &newPath); 1000 1001 /** 1002 * Returns the generator's certificate store (if any) 1003 * 1004 * @since 21.04 1005 */ 1006 CertificateStore *certificateStore() const; 1007 1008 public Q_SLOTS: 1009 /** 1010 * This slot is called whenever the user changes the @p rotation of 1011 * the document. 1012 */ 1013 void setRotation(int rotation); 1014 1015 /** 1016 * This slot is called whenever the user changes the page @p size 1017 * of the document. 1018 */ 1019 void setPageSize(const Okular::PageSize &size); 1020 1021 /** 1022 * Cancels the current search 1023 */ 1024 void cancelSearch(); 1025 1026 /** 1027 * Undo last edit command 1028 * @since 0.17 (KDE 4.11) 1029 */ 1030 void undo(); 1031 1032 /** 1033 * Redo last undone edit command 1034 * @since 0.17 (KDE 4.11) 1035 */ 1036 void redo(); 1037 1038 /** 1039 * Edit the text contents of the specified @p form on page @p page to be @p newContents. 1040 * The new text cursor position (@p newCursorPos), previous text cursor position (@p prevCursorPos), 1041 * and previous cursor anchor position will be restored by the undo / redo commands. 1042 * @since 0.17 (KDE 4.11) 1043 */ 1044 void editFormText(int pageNumber, Okular::FormFieldText *form, const QString &newContents, int newCursorPos, int prevCursorPos, int prevAnchorPos); 1045 1046 /** 1047 * Edit the selected list entries in @p form on page @p page to be @p newChoices. 1048 * @since 0.17 (KDE 4.11) 1049 */ 1050 void editFormList(int pageNumber, Okular::FormFieldChoice *form, const QList<int> &newChoices); 1051 1052 /** 1053 * Set the active choice in the combo box @p form on page @p page to @p newText 1054 * The new cursor position (@p newCursorPos), previous cursor position 1055 * (@p prevCursorPos), and previous anchor position (@p prevAnchorPos) 1056 * will be restored by the undo / redo commands. 1057 * 1058 * @since 0.17 (KDE 4.11) 1059 */ 1060 void editFormCombo(int pageNumber, Okular::FormFieldChoice *form, const QString &newText, int newCursorPos, int prevCursorPos, int prevAnchorPos); 1061 1062 /** 1063 * Set the states of the group of form buttons @p formButtons on page @p page to @p newButtonStates. 1064 * The lists @p formButtons and @p newButtonStates should be the same length and true values 1065 * in @p newButtonStates indicate that the corresponding entry in @p formButtons should be enabled. 1066 */ 1067 void editFormButtons(int pageNumber, const QList<Okular::FormFieldButton *> &formButtons, const QList<bool> &newButtonStates); 1068 1069 /** 1070 * Reloads the pixmaps for whole document 1071 * 1072 * @since 0.24 1073 */ 1074 void reloadDocument() const; 1075 1076 /** 1077 * Returns the part of document covered by the given signature @p info. 1078 * 1079 * @since 1.7 1080 */ 1081 QByteArray requestSignedRevisionData(const Okular::SignatureInfo &info); 1082 1083 /** 1084 * Refresh the pixmaps for the given @p pageNumber. 1085 * 1086 * @since 1.10 1087 */ 1088 void refreshPixmaps(int pageNumber); 1089 1090 Q_SIGNALS: 1091 /** 1092 * This signal is emitted whenever the document is about to close. 1093 * @since 1.5.3 1094 */ 1095 void aboutToClose(); 1096 1097 /** 1098 * This signal is emitted whenever an action requests a 1099 * document close operation. 1100 */ 1101 void close(); 1102 1103 /** 1104 * This signal is emitted whenever an action requests an 1105 * application quit operation. 1106 */ 1107 void quit(); 1108 1109 /** 1110 * This signal is emitted whenever an action requests a 1111 * find operation. 1112 */ 1113 void linkFind(); 1114 1115 /** 1116 * This signal is emitted whenever an action requests a 1117 * goto operation. 1118 */ 1119 void linkGoToPage(); 1120 1121 /** 1122 * This signal is emitted whenever an action requests a 1123 * start presentation operation. 1124 */ 1125 void linkPresentation(); 1126 1127 /** 1128 * This signal is emitted whenever an action requests an 1129 * end presentation operation. 1130 */ 1131 void linkEndPresentation(); 1132 1133 /** 1134 * This signal is emitted whenever an action requests an 1135 * open url operation for the given document @p url. 1136 */ 1137 void openUrl(const QUrl &url); 1138 1139 /** 1140 * This signal is emitted whenever an error occurred. 1141 * 1142 * @param text The description of the error. 1143 * @param duration The time in milliseconds the message should be shown to the user. 1144 */ 1145 void error(const QString &text, int duration); 1146 1147 /** 1148 * This signal is emitted to signal a warning. 1149 * 1150 * @param text The description of the warning. 1151 * @param duration The time in milliseconds the message should be shown to the user. 1152 */ 1153 void warning(const QString &text, int duration); 1154 1155 /** 1156 * This signal is emitted to signal a notice. 1157 * 1158 * @param text The description of the notice. 1159 * @param duration The time in milliseconds the message should be shown to the user. 1160 */ 1161 void notice(const QString &text, int duration); 1162 1163 /** 1164 * Emitted when a new font is found during the reading of the fonts of 1165 * the document. 1166 */ 1167 void gotFont(const Okular::FontInfo &font); 1168 1169 /** 1170 * Reports the progress when reading the fonts in the document. 1171 * 1172 * \param page is the page that was just finished to scan for fonts 1173 */ 1174 void fontReadingProgress(int page); 1175 1176 /** 1177 * Reports that the reading of the fonts in the document is finished. 1178 */ 1179 void fontReadingEnded(); 1180 1181 /** 1182 * Reports that the current search finished 1183 */ 1184 void searchFinished(int searchID, Okular::Document::SearchStatus endStatus); 1185 1186 /** 1187 * This signal is emitted whenever a source reference with the given parameters has been 1188 * activated. 1189 * 1190 * \param absFileName absolute name of the file. 1191 * \param line line number. 1192 * \param col column number. 1193 * \param handled should be set to 'true' if a slot handles this source reference; the 1194 * default action to launch the configured editor will then not be performed 1195 * by the document 1196 * 1197 * @since 0.14 (KDE 4.8) 1198 */ 1199 void sourceReferenceActivated(const QString &absFileName, int line, int col, bool *handled); 1200 1201 /** 1202 * This signal is emitted whenever an movie action is triggered and the UI should process it. 1203 */ 1204 void processMovieAction(const Okular::MovieAction *action); 1205 1206 /** 1207 * This signal is emitted whenever the availability of the undo function changes 1208 * @since 0.17 (KDE 4.11) 1209 */ 1210 void canUndoChanged(bool undoAvailable); 1211 1212 /** 1213 * This signal is emitted whenever the availability of the redo function changes 1214 * @since 0.17 (KDE 4.11) 1215 */ 1216 void canRedoChanged(bool redoAvailable); 1217 1218 /** 1219 * This signal is emitted whenever the undo history is clean (i.e. the same status the last time it was saved) 1220 * @since 1.3 1221 */ 1222 void undoHistoryCleanChanged(bool clean); 1223 1224 /** 1225 * This signal is emitted whenever an rendition action is triggered and the UI should process it. 1226 * 1227 * @since 0.16 (KDE 4.10) 1228 */ 1229 void processRenditionAction(const Okular::RenditionAction *action); 1230 1231 /** 1232 * This signal is emitted whenever the contents of the given @p annotation are changed by an undo 1233 * or redo action. 1234 * 1235 * The new contents (@p contents), cursor position (@p cursorPos), and anchor position (@p anchorPos) are 1236 * included 1237 * @since 0.17 (KDE 4.11) 1238 */ 1239 void annotationContentsChangedByUndoRedo(Okular::Annotation *annotation, const QString &contents, int cursorPos, int anchorPos); 1240 1241 /** 1242 * This signal is emitted whenever the text contents of the given text @p form on the given @p page 1243 * are changed by an undo or redo action. 1244 * 1245 * The new text contents (@p contents), cursor position (@p cursorPos), and anchor position (@p anchorPos) are 1246 * included 1247 * @since 0.17 (KDE 4.11) 1248 */ 1249 void formTextChangedByUndoRedo(int page, Okular::FormFieldText *form, const QString &contents, int cursorPos, int anchorPos); 1250 1251 /** 1252 * This signal is emitted whenever the selected @p choices for the given list @p form on the 1253 * given @p page are changed by an undo or redo action. 1254 * @since 0.17 (KDE 4.11) 1255 */ 1256 void formListChangedByUndoRedo(int page, Okular::FormFieldChoice *form, const QList<int> &choices); 1257 1258 /** 1259 * This signal is emitted whenever the active @p text for the given combo @p form on the 1260 * given @p page is changed by an undo or redo action. 1261 * @since 0.17 (KDE 4.11) 1262 */ 1263 void formComboChangedByUndoRedo(int page, Okular::FormFieldChoice *form, const QString &text, int cursorPos, int anchorPos); 1264 1265 /** 1266 * This signal is emitted whenever the state of the specified group of form buttons (@p formButtons) on the 1267 * given @p page is changed by an undo or redo action. 1268 * @since 0.17 (KDE 4.11) 1269 */ 1270 void formButtonsChangedByUndoRedo(int page, const QList<Okular::FormFieldButton *> &formButtons); 1271 1272 /** 1273 * This signal is emitted whenever a FormField was changed programmatically and the 1274 * according widget should be updated. 1275 * @since 1.4 1276 */ 1277 void refreshFormWidget(Okular::FormField *field); 1278 1279 private: 1280 /// @cond PRIVATE 1281 friend class DocumentPrivate; 1282 friend class ::DocumentItem; 1283 friend class EditAnnotationContentsCommand; 1284 friend class EditFormTextCommand; 1285 friend class EditFormListCommand; 1286 friend class EditFormComboCommand; 1287 friend class EditFormButtonsCommand; 1288 /// @endcond 1289 DocumentPrivate *const d; 1290 1291 Q_DISABLE_COPY(Document) 1292 }; 1293 1294 /** 1295 * @short A view on the document. 1296 * 1297 * The Viewport structure is the 'current view' over the document. Contained 1298 * data is broadcasted between observers to synchronize their viewports to get 1299 * the 'I scroll one view and others scroll too' views. 1300 */ 1301 class OKULARCORE_EXPORT DocumentViewport 1302 { 1303 public: 1304 /** 1305 * Creates a new viewport for the given page @p number. 1306 */ 1307 explicit DocumentViewport(int number = -1); 1308 1309 /** 1310 * Creates a new viewport from the given @p xmlDesc. 1311 */ 1312 explicit DocumentViewport(const QString &xmlDesc); 1313 1314 /** 1315 * Returns the viewport as xml description. 1316 */ 1317 QString toString() const; 1318 1319 /** 1320 * Returns whether the viewport is valid. 1321 */ 1322 bool isValid() const; 1323 1324 /** 1325 * @internal 1326 */ 1327 bool operator==(const DocumentViewport &other) const; 1328 bool operator<(const DocumentViewport &other) const; 1329 1330 /** 1331 * The number of the page nearest the center of the viewport. 1332 */ 1333 int pageNumber; 1334 1335 /** 1336 * Describes the relative position of the viewport. 1337 */ 1338 enum Position { 1339 Center = 1, ///< Relative to the center of the page. 1340 TopLeft = 2 ///< Relative to the top left corner of the page. 1341 }; 1342 1343 /** 1344 * If 'rePos.enabled == true' then this structure contains the 1345 * viewport center or top left depending on the value of pos. 1346 */ 1347 struct { 1348 bool enabled; 1349 double normalizedX; 1350 double normalizedY; 1351 Position pos; 1352 } rePos; 1353 1354 /** 1355 * If 'autoFit.enabled == true' then the page must be autofit in the viewport. 1356 */ 1357 struct { 1358 bool enabled; 1359 bool width; 1360 bool height; 1361 } autoFit; 1362 }; 1363 1364 /** 1365 * @short A DOM tree that describes the Table of Contents. 1366 * 1367 * The Synopsis (TOC or Table Of Contents for friends) is represented via 1368 * a dom tree where each node has an internal name (displayed in the TOC) 1369 * and one or more attributes. 1370 * 1371 * In the tree the tag name is the 'screen' name of the entry. A tag can have 1372 * attributes. Here follows the list of tag attributes with meaning: 1373 * - Destination: A string description of the referred viewport 1374 * - DestinationName: A 'named reference' to the viewport that must be converted 1375 * using metaData( "NamedViewport", viewport_name ) 1376 * - ExternalFileName: A document to be opened, whose destination is specified 1377 * with Destination or DestinationName 1378 * - Open: a boolean saying whether its TOC branch is open or not (default: false) 1379 * - URL: a URL to be open as destination; if set, no other Destination* or 1380 * ExternalFileName entry is used 1381 */ 1382 class OKULARCORE_EXPORT DocumentSynopsis : public QDomDocument 1383 { 1384 public: 1385 /** 1386 * Creates a new document synopsis object. 1387 */ 1388 DocumentSynopsis(); 1389 1390 /** 1391 * Creates a new document synopsis object with the given 1392 * @p document as parent node. 1393 */ 1394 explicit DocumentSynopsis(const QDomDocument &document); 1395 }; 1396 1397 /** 1398 * @short An embedded file into the document. 1399 * 1400 * This class represents a sort of interface of an embedded file in a document. 1401 * 1402 * Generators \b must re-implement its members to give the all the information 1403 * about an embedded file, like its name, its description, the date of creation 1404 * and modification, and the real data of the file. 1405 */ 1406 class OKULARCORE_EXPORT EmbeddedFile 1407 { 1408 public: 1409 /** 1410 * Creates a new embedded file. 1411 */ 1412 EmbeddedFile(); 1413 1414 /** 1415 * Destroys the embedded file. 1416 */ 1417 virtual ~EmbeddedFile(); 1418 1419 EmbeddedFile(const EmbeddedFile &) = delete; 1420 EmbeddedFile &operator=(const EmbeddedFile &) = delete; 1421 1422 /** 1423 * Returns the name of the file 1424 */ 1425 virtual QString name() const = 0; 1426 1427 /** 1428 * Returns the description of the file, or an empty string if not 1429 * available 1430 */ 1431 virtual QString description() const = 0; 1432 1433 /** 1434 * Returns the real data representing the file contents 1435 */ 1436 virtual QByteArray data() const = 0; 1437 1438 /** 1439 * Returns the size (in bytes) of the file, if available, or -1 otherwise. 1440 * 1441 * @note this method should be a fast way to know the size of the file 1442 * with no need to extract all the data from it 1443 */ 1444 virtual int size() const = 0; 1445 1446 /** 1447 * Returns the modification date of the file, or an invalid date 1448 * if not available 1449 */ 1450 virtual QDateTime modificationDate() const = 0; 1451 1452 /** 1453 * Returns the creation date of the file, or an invalid date 1454 * if not available 1455 */ 1456 virtual QDateTime creationDate() const = 0; 1457 }; 1458 1459 /** 1460 * @short An area of a specified page 1461 */ 1462 class OKULARCORE_EXPORT VisiblePageRect 1463 { 1464 public: 1465 /** 1466 * Creates a new visible page rectangle. 1467 * 1468 * @param pageNumber The page number where the rectangle is located. 1469 * @param rectangle The rectangle in normalized coordinates. 1470 */ 1471 explicit VisiblePageRect(int pageNumber = -1, const NormalizedRect &rectangle = NormalizedRect()); 1472 1473 /** 1474 * The page number where the rectangle is located. 1475 */ 1476 int pageNumber; 1477 1478 /** 1479 * The rectangle in normalized coordinates. 1480 */ 1481 NormalizedRect rect; 1482 }; 1483 1484 /** 1485 * @short Data needed to create a new signature 1486 * 1487 * @since 21.04 1488 */ 1489 class OKULARCORE_EXPORT NewSignatureData 1490 { 1491 public: 1492 NewSignatureData(); 1493 ~NewSignatureData(); 1494 NewSignatureData(const NewSignatureData &) = delete; 1495 NewSignatureData &operator=(const NewSignatureData &) = delete; 1496 1497 QString certNickname() const; 1498 void setCertNickname(const QString &certNickname); 1499 1500 QString certSubjectCommonName() const; 1501 void setCertSubjectCommonName(const QString &certSubjectCommonName); 1502 1503 QString password() const; 1504 void setPassword(const QString &password); 1505 1506 int page() const; 1507 void setPage(int page); 1508 1509 NormalizedRect boundingRectangle() const; 1510 void setBoundingRectangle(const NormalizedRect &rect); 1511 1512 private: 1513 NewSignatureDataPrivate *const d; 1514 }; 1515 1516 } 1517 1518 Q_DECLARE_METATYPE(Okular::DocumentInfo::Key) 1519 Q_DECLARE_OPERATORS_FOR_FLAGS(Okular::Document::PixmapRequestFlags) 1520 1521 #endif 1522 1523 /* kate: replace-tabs on; indent-width 4; */ 1524