1 // Copyright 2012 The Chromium Authors
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 #ifndef PDF_PDF_ENGINE_H_
6 #define PDF_PDF_ENGINE_H_
14 #include "base/containers/span.h"
15 #include "base/functional/callback.h"
16 #include "base/time/time.h"
17 #include "base/values.h"
18 #include "build/build_config.h"
19 #include "pdf/document_layout.h"
20 #include "printing/mojom/print.mojom-forward.h"
21 #include "third_party/abseil-cpp/absl/types/optional.h"
22 #include "third_party/skia/include/core/SkColor.h"
23 #include "ui/base/cursor/mojom/cursor_type.mojom-forward.h"
24 #include "ui/base/window_open_disposition.h"
25 #include "ui/gfx/geometry/point_f.h"
26 #include "ui/gfx/geometry/rect.h"
27 #include "ui/gfx/geometry/rect_f.h"
37 struct WebPrintParams;
48 namespace chrome_pdf {
52 struct AccessibilityActionData;
53 struct AccessibilityFocusInfo;
54 struct AccessibilityLinkInfo;
55 struct AccessibilityHighlightInfo;
56 struct AccessibilityImageInfo;
57 struct AccessibilityTextFieldInfo;
58 struct AccessibilityTextRunInfo;
59 struct DocumentAttachmentInfo;
60 struct DocumentMetadata;
62 using SendThumbnailCallback = base::OnceCallback<void(Thumbnail)>;
64 enum class FontMappingMode {
65 // Do not perform font mapping.
67 // Perform font mapping in renderer processes using Blink/content APIs.
71 enum class DocumentPermission {
78 // Do one time initialization of the SDK.
79 // If `enable_v8` is false, then the PDFEngine will not be able to run
81 // When `use_skia` is true, the PDFEngine will use Skia renderer. Otherwise, it
82 // will use AGG renderer.
83 void InitializeSDK(bool enable_v8,
85 FontMappingMode font_mapping_mode);
86 // Tells the SDK that we're shutting down.
89 // This class encapsulates a PDF rendering engine.
92 // Maximum number of parameters a nameddest view can contain.
93 static constexpr size_t kMaxViewParams = 4;
95 enum class FocusFieldType {
96 // Focus is not on any form field.
98 // Focus is on a form text field or form combobox text field.
100 // Focus is on a non-text field.
104 // Named destination in a document.
105 struct NamedDestination {
106 // 0-based page number.
109 // View fit type (see table 8.2 "Destination syntax" on page 582 of PDF
110 // Reference 1.7). Empty string if not present.
113 // Number of parameters for the view.
114 unsigned long num_params;
116 // Parameters for the view. Their meaning depends on the `view` and their
117 // number is defined by `num_params` but is at most `kMaxViewParams`. Note:
118 // If a parameter stands for the x/y coordinates, it should be transformed
119 // into the corresponding in-screen coordinates before it's sent to the
121 float params[kMaxViewParams];
123 // A string of parameters for view fit type XYZ in the format of "x,y,zoom",
124 // where x and y parameters are the in-screen coordinates and zoom is the
125 // zoom level. If a parameter is "null", then current value of that
126 // parameter in the viewport should be retained. Note: This string is empty
127 // if the view's fit type is not XYZ.
128 std::string xyz_params;
131 // The interface that's provided to the rendering engine.
134 virtual ~Client() = default;
136 // Proposes a document layout to the client. For the proposed layout to
137 // become effective, the client must call PDFEngine::ApplyDocumentLayout()
138 // with the new layout options (although this call can be asynchronous).
139 virtual void ProposeDocumentLayout(const DocumentLayout& layout) = 0;
141 // Informs the client that the given rect needs to be repainted.
142 virtual void Invalidate(const gfx::Rect& rect) {}
144 // Informs the client to scroll the plugin area by the given offset.
145 virtual void DidScroll(const gfx::Vector2d& offset) {}
147 // Scroll the horizontal/vertical scrollbars to a given position.
148 // Values are in screen coordinates, where 0 is the top/left of the document
149 // and a positive value is the distance in pixels from that line.
150 virtual void ScrollToX(int x_screen_coords) {}
151 virtual void ScrollToY(int y_screen_coords) {}
153 // Scroll by a given delta relative to the current position.
154 virtual void ScrollBy(const gfx::Vector2d& delta) {}
156 // Scroll to zero-based `page`.
157 virtual void ScrollToPage(int page) {}
159 // Navigate to the given url.
160 virtual void NavigateTo(const std::string& url,
161 WindowOpenDisposition disposition) {}
163 // Navigate to the given destination. Zero-based `page` index. `x`, `y` and
164 // `zoom` are optional and can be nullptr.
165 virtual void NavigateToDestination(int page,
168 const float* zoom) {}
170 // Updates the cursor.
171 virtual void UpdateCursor(ui::mojom::CursorType new_cursor_type) {}
173 // Updates the tick marks in the vertical scrollbar.
174 virtual void UpdateTickMarks(const std::vector<gfx::Rect>& tickmarks) {}
176 // Updates the number of find results for the current search term. If
177 // there are no matches 0 should be passed in. Only when the plugin has
178 // finished searching should it pass in the final count with `final_result`
180 virtual void NotifyNumberOfFindResultsChanged(int total,
181 bool final_result) {}
183 // Updates the index of the currently selected search item. Set
184 // `final_result` to true only when there is no subsequent
185 // `NotifyNumberOfFindResultsChanged()` call.
186 virtual void NotifySelectedFindResultChanged(int current_find_index,
187 bool final_result) {}
189 virtual void NotifyTouchSelectionOccurred() {}
191 // Prompts the user for a password to open this document. The callback is
192 // called when the password is retrieved.
193 virtual void GetDocumentPassword(
194 base::OnceCallback<void(const std::string&)> callback) {}
196 // Play a "beeping" sound.
197 virtual void Beep() {}
199 // Puts up an alert with the given message.
200 virtual void Alert(const std::string& message) {}
202 // Puts up a confirm with the given message, and returns true if the user
203 // presses OK, or false if they press cancel.
204 virtual bool Confirm(const std::string& message) = 0;
206 // Puts up a prompt with the given message and default answer and returns
208 virtual std::string Prompt(const std::string& question,
209 const std::string& default_answer) = 0;
211 // Returns the url of the pdf.
212 virtual std::string GetURL() = 0;
215 virtual void Email(const std::string& to,
216 const std::string& cc,
217 const std::string& bcc,
218 const std::string& subject,
219 const std::string& body) {}
221 // Put up the print dialog.
222 virtual void Print() {}
224 // Submit the data using HTTP POST.
225 virtual void SubmitForm(const std::string& url,
229 // Creates and returns new URL loader for partial document requests.
230 virtual std::unique_ptr<UrlLoader> CreateUrlLoader() = 0;
232 // Searches the given string for "term" and returns the results. Unicode-
234 struct SearchStringResult {
238 virtual std::vector<SearchStringResult> SearchString(
239 const char16_t* string,
240 const char16_t* term,
241 bool case_sensitive) = 0;
243 // Notifies the client that the document has finished loading.
244 virtual void DocumentLoadComplete() {}
246 // Notifies the client that the document has failed to load.
247 virtual void DocumentLoadFailed() {}
249 // Notifies that an unsupported feature in the PDF was encountered.
250 virtual void DocumentHasUnsupportedFeature(const std::string& feature) {}
252 // Notifies the client about document load progress.
253 virtual void DocumentLoadProgress(uint32_t available, uint32_t doc_size) {}
255 // Notifies the client about focus changes for form fields.
256 virtual void FormFieldFocusChange(FocusFieldType type) {}
258 // Returns true if the plugin has been opened within print preview.
259 virtual bool IsPrintPreview() const = 0;
261 // Get the background color of the PDF.
262 virtual SkColor GetBackgroundColor() const = 0;
264 // Sets selection status.
265 virtual void SetIsSelecting(bool is_selecting) {}
267 virtual void SelectionChanged(const gfx::Rect& left,
268 const gfx::Rect& right) {}
270 // The caret position in the editable form (if applicable) changed.
271 virtual void CaretChanged(const gfx::Rect& caret_rect) {}
273 // Notifies the client that the PDF has been edited.
274 virtual void EnteredEditMode() {}
276 // Notifies the client about focus changes for the document.
277 virtual void DocumentFocusChanged(bool document_has_focus) {}
279 // Sets selected text.
280 virtual void SetSelectedText(const std::string& selected_text) = 0;
282 // Sets the link under cursor.
283 virtual void SetLinkUnderCursor(const std::string& link_under_cursor) = 0;
285 // If the link cannot be converted to JS payload struct, then it is not
286 // possible to pass it to JS. In this case, ignore the link like other PDF
288 // See https://crbug.com/312882 for an example.
289 virtual bool IsValidLink(const std::string& url) = 0;
292 virtual ~PDFEngine() = default;
294 // Most of these functions are similar to the Pepper functions of the same
295 // name, so not repeating the description here unless it's different.
296 virtual void PageOffsetUpdated(const gfx::Vector2d& page_offset) = 0;
297 virtual void PluginSizeUpdated(const gfx::Size& size) = 0;
298 virtual void ScrolledToXPosition(int position) = 0;
299 virtual void ScrolledToYPosition(int position) = 0;
300 // Paint is called a series of times. Before these n calls are made, PrePaint
301 // is called once. After Paint is called n times, PostPaint is called once.
302 virtual void PrePaint() = 0;
303 virtual void Paint(const gfx::Rect& rect,
304 SkBitmap& image_data,
305 std::vector<gfx::Rect>& ready,
306 std::vector<gfx::Rect>& pending) = 0;
307 virtual void PostPaint() = 0;
308 virtual bool HandleInputEvent(const blink::WebInputEvent& event) = 0;
309 virtual void PrintBegin() = 0;
310 virtual std::vector<uint8_t> PrintPages(
311 const std::vector<int>& page_index,
312 const blink::WebPrintParams& print_params) = 0;
313 virtual void PrintEnd() = 0;
314 virtual void StartFind(const std::u16string& text, bool case_sensitive) = 0;
315 virtual bool SelectFindResult(bool forward) = 0;
316 virtual void StopFind() = 0;
317 virtual void ZoomUpdated(double new_zoom_level) = 0;
318 virtual void RotateClockwise() = 0;
319 virtual void RotateCounterclockwise() = 0;
320 virtual bool IsReadOnly() const = 0;
321 virtual void SetReadOnly(bool enable) = 0;
322 virtual void SetDocumentLayout(DocumentLayout::PageSpread page_spread) = 0;
323 virtual void DisplayAnnotations(bool display) = 0;
325 // Applies the document layout options proposed by a call to
326 // PDFEngine::Client::ProposeDocumentLayout(), returning the overall size of
327 // the new effective layout.
328 virtual gfx::Size ApplyDocumentLayout(
329 const DocumentLayout::Options& options) = 0;
331 virtual std::string GetSelectedText() = 0;
332 // Returns true if focus is within an editable form text area.
333 virtual bool CanEditText() const = 0;
334 // Returns true if focus is within an editable form text area and the text
336 virtual bool HasEditableText() const = 0;
337 // Replace selected text within an editable form text area with another
338 // string. If there is no selected text, append the replacement text after the
339 // current caret position.
340 virtual void ReplaceSelection(const std::string& text) = 0;
341 // Methods to check if undo/redo is possible, and to perform them.
342 virtual bool CanUndo() const = 0;
343 virtual bool CanRedo() const = 0;
344 virtual void Undo() = 0;
345 virtual void Redo() = 0;
346 // Handles actions invoked by Accessibility clients.
347 virtual void HandleAccessibilityAction(
348 const AccessibilityActionData& action_data) = 0;
349 virtual std::string GetLinkAtPosition(const gfx::Point& point) = 0;
350 // Checks the permissions associated with this document.
351 virtual bool HasPermission(DocumentPermission permission) const = 0;
352 virtual void SelectAll() = 0;
353 // Gets the list of DocumentAttachmentInfo from the document.
354 virtual const std::vector<DocumentAttachmentInfo>&
355 GetDocumentAttachmentInfoList() const = 0;
356 // Gets the content of an attachment by the attachment's `index`. `index`
357 // must be in the range of [0, attachment_count-1), where `attachment_count`
358 // is the number of attachments embedded in the document.
359 // The caller of this method is responsible for checking whether the
360 // attachment is readable, attachment size is not 0 byte, and the return
361 // value's size matches the corresponding DocumentAttachmentInfo's
363 virtual std::vector<uint8_t> GetAttachmentData(size_t index) = 0;
364 // Gets metadata about the document.
365 virtual const DocumentMetadata& GetDocumentMetadata() const = 0;
366 // Gets the number of pages in the document.
367 virtual int GetNumberOfPages() const = 0;
368 // Gets the named destination by name.
369 virtual absl::optional<PDFEngine::NamedDestination> GetNamedDestination(
370 const std::string& destination) = 0;
371 // Gets the index of the most visible page, or -1 if none are visible.
372 virtual int GetMostVisiblePage() = 0;
373 // Gets the rectangle of the page not including the shadow.
374 virtual gfx::Rect GetPageBoundsRect(int index) = 0;
375 // Gets the rectangle of the page excluding any additional areas.
376 virtual gfx::Rect GetPageContentsRect(int index) = 0;
377 // Returns a page's rect in screen coordinates, as well as its surrounding
378 // border areas and bottom separator.
379 virtual gfx::Rect GetPageScreenRect(int page_index) const = 0;
380 // Return a page's bounding box rectangle, or an empty rectangle if
381 // `page_index` is invalid.
382 virtual gfx::RectF GetPageBoundingBox(int page_index) = 0;
383 // Set color / grayscale rendering modes.
384 virtual void SetGrayscale(bool grayscale) = 0;
385 // Get the number of characters on a given page.
386 virtual int GetCharCount(int page_index) = 0;
387 // Get the bounds in page pixels of a character on a given page.
388 virtual gfx::RectF GetCharBounds(int page_index, int char_index) = 0;
389 // Get a given unicode character on a given page.
390 virtual uint32_t GetCharUnicode(int page_index, int char_index) = 0;
391 // Given a start char index, find the longest continuous run of text that's
392 // in a single direction and with the same text style. Return a filled out
393 // AccessibilityTextRunInfo on success or absl::nullopt on failure. e.g. When
394 // `start_char_index` is out of bounds.
395 virtual absl::optional<AccessibilityTextRunInfo> GetTextRunInfo(
397 int start_char_index) = 0;
398 // For all the links on page `page_index`, get their urls, underlying text
399 // ranges and bounding boxes.
400 virtual std::vector<AccessibilityLinkInfo> GetLinkInfo(
402 const std::vector<AccessibilityTextRunInfo>& text_runs) = 0;
403 // For all the images in page `page_index`, get their alt texts and bounding
404 // boxes. If the alt text is empty or unavailable, and if the user has
405 // requested that the OCR service tag the PDF so that it is made accessible,
406 // transfer the raw image pixels in the `image_data` field. Otherwise do not
407 // populate the `image_data` field.
408 virtual std::vector<AccessibilityImageInfo> GetImageInfo(
410 uint32_t text_run_count) = 0;
411 // Returns the image as a 32-bit bitmap format for OCR.
412 virtual SkBitmap GetImageForOcr(int page_index, int image_index) = 0;
413 // For all the highlights in page `page_index`, get their underlying text
414 // ranges and bounding boxes.
415 virtual std::vector<AccessibilityHighlightInfo> GetHighlightInfo(
417 const std::vector<AccessibilityTextRunInfo>& text_runs) = 0;
418 // For all the text fields in page `page_index`, get their properties like
419 // name, value, bounding boxes etc.
420 virtual std::vector<AccessibilityTextFieldInfo> GetTextFieldInfo(
422 uint32_t text_run_count) = 0;
424 // Gets the PDF document's print scaling preference. True if the document can
426 virtual bool GetPrintScaling() = 0;
427 // Returns number of copies to be printed.
428 virtual int GetCopiesToPrint() = 0;
429 // Returns the duplex setting.
430 virtual printing::mojom::DuplexMode GetDuplexMode() = 0;
431 // Returns the uniform page size of the document in points. Returns
432 // `absl::nullopt` if the document has more than one page size.
433 virtual absl::optional<gfx::Size> GetUniformPageSizePoints() = 0;
435 // Returns a list of Values of Bookmarks. Each Bookmark is a dictionary Value
436 // which contains the following key/values:
437 // - "title" - a string Value.
438 // - "page" - an int Value.
439 // - "children" - a list of Values, with each entry containing
440 // a dictionary Value of the same structure.
441 virtual base::Value::List GetBookmarks() = 0;
443 // Append blank pages to make a 1-page document to a `num_pages` document.
444 // Always retain the first page data.
445 virtual void AppendBlankPages(size_t num_pages) = 0;
446 // Append the first page of the document loaded with the `engine` to this
447 // document at page `index`.
448 virtual void AppendPage(PDFEngine* engine, int index) = 0;
450 virtual std::vector<uint8_t> GetSaveData() = 0;
452 virtual void SetCaretPosition(const gfx::Point& position) = 0;
453 virtual void MoveRangeSelectionExtent(const gfx::Point& extent) = 0;
454 virtual void SetSelectionBounds(const gfx::Point& base,
455 const gfx::Point& extent) = 0;
456 virtual void GetSelection(uint32_t* selection_start_page_index,
457 uint32_t* selection_start_char_index,
458 uint32_t* selection_end_page_index,
459 uint32_t* selection_end_char_index) = 0;
461 // Remove focus from form widgets, consolidating the user input.
462 virtual void KillFormFocus() = 0;
464 // Notify whether the PDF currently has the focus or not.
465 virtual void UpdateFocus(bool has_focus) = 0;
467 // Returns the focus info of current focus item.
468 virtual AccessibilityFocusInfo GetFocusInfo() = 0;
470 virtual uint32_t GetLoadedByteSize() = 0;
471 virtual bool ReadLoadedBytes(uint32_t length, void* buffer) = 0;
473 // Requests for a thumbnail to be sent using a callback when the page is ready
474 // to be rendered. `send_callback` is run with the thumbnail data when ready.
475 virtual void RequestThumbnail(int page_index,
476 float device_pixel_ratio,
477 SendThumbnailCallback send_callback) = 0;
480 // Interface for exports that wrap the PDF engine.
481 class PDFEngineExports {
483 struct RenderingSettings {
484 RenderingSettings(const gfx::Size& dpi,
485 const gfx::Rect& bounds,
487 bool stretch_to_bounds,
488 bool keep_aspect_ratio,
489 bool center_in_bounds,
492 bool render_for_printing);
493 RenderingSettings(const RenderingSettings& that);
498 bool stretch_to_bounds;
499 bool keep_aspect_ratio;
500 bool center_in_bounds;
503 bool render_for_printing;
506 PDFEngineExports() {}
507 virtual ~PDFEngineExports() {}
509 static PDFEngineExports* Get();
511 #if BUILDFLAG(IS_CHROMEOS)
512 // See the definition of CreateFlattenedPdf in pdf.cc for details.
513 virtual std::vector<uint8_t> CreateFlattenedPdf(
514 base::span<const uint8_t> input_buffer) = 0;
515 #endif // BUILDFLAG(IS_CHROMEOS)
517 #if BUILDFLAG(IS_WIN)
518 // See the definition of RenderPDFPageToDC in pdf.cc for details.
519 virtual bool RenderPDFPageToDC(base::span<const uint8_t> pdf_buffer,
521 const RenderingSettings& settings,
524 virtual void SetPDFUsePrintMode(int mode) = 0;
525 #endif // BUILDFLAG(IS_WIN)
527 // See the definition of RenderPDFPageToBitmap in pdf.cc for details.
528 virtual bool RenderPDFPageToBitmap(base::span<const uint8_t> pdf_buffer,
530 const RenderingSettings& settings,
531 void* bitmap_buffer) = 0;
533 // See the definition of ConvertPdfPagesToNupPdf in pdf.cc for details.
534 virtual std::vector<uint8_t> ConvertPdfPagesToNupPdf(
535 std::vector<base::span<const uint8_t>> input_buffers,
536 size_t pages_per_sheet,
537 const gfx::Size& page_size,
538 const gfx::Rect& printable_area) = 0;
540 // See the definition of ConvertPdfDocumentToNupPdf in pdf.cc for details.
541 virtual std::vector<uint8_t> ConvertPdfDocumentToNupPdf(
542 base::span<const uint8_t> input_buffer,
543 size_t pages_per_sheet,
544 const gfx::Size& page_size,
545 const gfx::Rect& printable_area) = 0;
547 virtual bool GetPDFDocInfo(base::span<const uint8_t> pdf_buffer,
549 float* max_page_width) = 0;
551 // Whether the PDF is Tagged (see 10.7 "Tagged PDF" in PDF Reference 1.7).
552 // Returns true if it's a tagged (accessible) PDF, false if it's a valid
553 // PDF but untagged, and nullopt if the PDF can't be parsed.
554 virtual absl::optional<bool> IsPDFDocTagged(
555 base::span<const uint8_t> pdf_buffer) = 0;
557 // Given a tagged PDF (see IsPDFDocTagged, above), return the portion of
558 // the structure tree for a given page as a hierarchical tree of base::Values.
559 virtual base::Value GetPDFStructTreeForPage(
560 base::span<const uint8_t> pdf_buffer,
563 // See the definition of GetPDFPageSizeByIndex in pdf.cc for details.
564 virtual absl::optional<gfx::SizeF> GetPDFPageSizeByIndex(
565 base::span<const uint8_t> pdf_buffer,
569 } // namespace chrome_pdf
571 #endif // PDF_PDF_ENGINE_H_