| // Copyright 2024 The Chromium Authors | |
| // Use of this source code is governed by a BSD-style license that can be | |
| // found in the LICENSE file. | |
| #ifndef PDF_PDF_INK_MODULE_H_ | |
| #define PDF_PDF_INK_MODULE_H_ | |
| #include <map> | |
| #include <memory> | |
| #include <optional> | |
| #include <set> | |
| #include <variant> | |
| #include <vector> | |
| #include "base/containers/flat_set.h" | |
| #include "base/gtest_prod_util.h" | |
| #include "base/memory/raw_ref.h" | |
| #include "base/memory/weak_ptr.h" | |
| #include "base/time/time.h" | |
| #include "base/timer/timer.h" | |
| #include "base/values.h" | |
| #include "pdf/buildflags.h" | |
| #include "pdf/page_orientation.h" | |
| #include "pdf/pdf_ink_annotation_mode.h" | |
| #include "pdf/pdf_ink_brush.h" | |
| #include "pdf/pdf_ink_ids.h" | |
| #include "pdf/pdf_ink_undo_redo_model.h" | |
| #include "pdf/ui/thumbnail.h" | |
| #include "third_party/ink/src/ink/geometry/affine_transform.h" | |
| #include "third_party/ink/src/ink/geometry/partitioned_mesh.h" | |
| #include "third_party/ink/src/ink/strokes/in_progress_stroke.h" | |
| #include "third_party/ink/src/ink/strokes/input/stroke_input.h" | |
| #include "third_party/ink/src/ink/strokes/stroke.h" | |
| #include "third_party/skia/include/core/SkRect.h" | |
| #include "ui/gfx/geometry/point_f.h" | |
| #include "ui/gfx/geometry/transform.h" | |
| static_assert(BUILDFLAG(ENABLE_PDF_INK2), "ENABLE_PDF_INK2 not set to true"); | |
| class SkCanvas; | |
| namespace blink { | |
| class WebKeyboardEvent; | |
| class WebInputEvent; | |
| class WebMouseEvent; | |
| class WebPointerProperties; | |
| class WebTouchEvent; | |
| } // namespace blink | |
| namespace chrome_pdf { | |
| class PdfInkModuleClient; | |
| class PdfInkSignatureCreationHandler; | |
| class PdfInkModule { | |
| public: | |
| explicit PdfInkModule(PdfInkModuleClient& client); | |
| PdfInkModule(const PdfInkModule&) = delete; | |
| PdfInkModule& operator=(const PdfInkModule&) = delete; | |
| ~PdfInkModule(); | |
| bool enabled() const { return mode_ != InkAnnotationMode::kOff; } | |
| // Returns whether the text selection change event should be blocked to | |
| // prevent modifying the clipboard content. | |
| bool ShouldBlockTextSelectionChanged(); | |
| // Determines if there are any in-progress strokes to be drawn. | |
| bool HasInputsToDraw() const; | |
| // Draws any in-progress strokes into `canvas`. Must either be in text | |
| // highlighting state or in drawing stroke state with non-empty | |
| // `drawing_stroke_state().in_progress_strokes`. | |
| void Draw(SkCanvas& canvas); | |
| // Returns whether the event was handled or not. | |
| bool HandleInputEvent(const blink::WebInputEvent& event); | |
| // Returns whether the message was handled or not. | |
| bool OnMessage(const base::DictValue& message); | |
| // Informs PdfInkModule that the plugin geometry changed. | |
| void OnGeometryChanged(); | |
| // Reports session metrics (e.g. net text annotation count change) when the | |
| // PDF is being saved. | |
| void RecordMetricsOnSave(); | |
| // For testing only. Returns the current `PdfInkBrush` used to draw strokes, | |
| // or nullptr if there is no brush because `PdfInkModule` is not in the | |
| // drawing state. | |
| const PdfInkBrush* GetPdfInkBrushForTesting() const; | |
| private: | |
| friend class PdfInkModuleStrokeTest; | |
| FRIEND_TEST_ALL_PREFIXES(PdfInkModuleTest, HandleSetAnnotationModeMessage); | |
| // A stroke that has been completed, its ID, and whether it should be drawn | |
| // or not. | |
| struct FinishedStrokeState { | |
| FinishedStrokeState(ink::Stroke stroke, InkStrokeId id); | |
| FinishedStrokeState(const FinishedStrokeState&) = delete; | |
| FinishedStrokeState& operator=(const FinishedStrokeState&) = delete; | |
| FinishedStrokeState(FinishedStrokeState&&) noexcept; | |
| FinishedStrokeState& operator=(FinishedStrokeState&&) noexcept; | |
| ~FinishedStrokeState(); | |
| // Coordinates for each stroke are stored in a canonical format specified in | |
| // pdf_ink_transform.h. | |
| ink::Stroke stroke; | |
| // A unique ID to identify this stroke. | |
| InkStrokeId id; | |
| bool should_draw = true; | |
| }; | |
| // Each page of a document can have many strokes. Each stroke is restricted | |
| // to just one page. | |
| // The elements are stored with IDs in an increasing order. | |
| using PageStrokes = std::vector<FinishedStrokeState>; | |
| // Mapping of a 0-based page index to the strokes for that page. | |
| using DocumentStrokesMap = std::map<int, PageStrokes>; | |
| // A shape that was loaded from a "V2" path from the PDF itself, its ID, and | |
| // whether it should be drawn or not. | |
| struct LoadedV2ShapeState { | |
| LoadedV2ShapeState(ink::PartitionedMesh shape, InkModeledShapeId id); | |
| LoadedV2ShapeState(const LoadedV2ShapeState&) = delete; | |
| LoadedV2ShapeState& operator=(const LoadedV2ShapeState&) = delete; | |
| LoadedV2ShapeState(LoadedV2ShapeState&&) noexcept; | |
| LoadedV2ShapeState& operator=(LoadedV2ShapeState&&) noexcept; | |
| ~LoadedV2ShapeState(); | |
| // Coordinates for each shape are stored in a canonical format specified in | |
| // pdf_ink_transform.h. | |
| ink::PartitionedMesh shape; | |
| // A unique ID to identify this shape. | |
| InkModeledShapeId id; | |
| bool should_draw = true; | |
| }; | |
| // Like PageStrokes, but for shapes created from "V2" paths in the PDF. | |
| using PageV2InkPathShapes = std::vector<LoadedV2ShapeState>; | |
| // Like DocumentStrokesMap, but for PageV2InkPathShapes. | |
| using DocumentV2InkPathShapesMap = std::map<int, PageV2InkPathShapes>; | |
| struct EventDetails { | |
| // The event position. Coordinates match the screen-based position that | |
| // are provided during stroking from `blink::WebMouseEvent` positions. | |
| gfx::PointF position; | |
| // The event time. | |
| base::TimeTicks timestamp; | |
| // The type of tool used to generate the input. | |
| ink::StrokeInput::ToolType tool_type = ink::StrokeInput::ToolType::kUnknown; | |
| }; | |
| struct DrawingStrokeState { | |
| DrawingStrokeState(); | |
| DrawingStrokeState(const DrawingStrokeState&) = delete; | |
| DrawingStrokeState& operator=(const DrawingStrokeState&) = delete; | |
| ~DrawingStrokeState(); | |
| // The current brush type to use for drawing strokes. | |
| PdfInkBrush::Type brush_type; | |
| std::optional<base::TimeTicks> start_time; | |
| // The 0-based page index which is currently being stroked. | |
| int page_index = -1; | |
| // Details from the last input. Used after stroking has already started, | |
| // for invalidation and for extrapolating where a stroke crosses the page | |
| // boundary. Also used to compensate for missed events, when an end event | |
| // was consumed by a different view and this is detected afterwards when | |
| // PdfInkModule finally sees input events again. | |
| std::optional<EventDetails> input_last_event; | |
| // The in-progress strokes for the current stroking action. A new stroke | |
| // will be necessary each time the input leaves the page during collection | |
| // and then returns back into the original starting page. The coordinates | |
| // added into each stroke are stored in a canonical format specified in | |
| // pdf_ink_transform.h. | |
| std::vector<ink::InProgressStroke> in_progress_strokes; | |
| }; | |
| // Generates globally unique, monotonically increasing IDs for all user-added | |
| // annotations (e.g., strokes and text). | |
| // | |
| // All user-added annotation types must share this single ID sequence. | |
| // `PdfInkUndoRedoModel` relies on the underlying numerical value representing | |
| // the chronological order of creation across all types to efficiently | |
| // truncate the redo stack. | |
| class IdGenerator { | |
| public: | |
| IdGenerator(); | |
| ~IdGenerator(); | |
| // Returns an available stroke ID and advance the next available ID | |
| // internally. | |
| InkStrokeId GetStrokeIdAndAdvance(); | |
| // Returns an available text ID and advance the next available ID | |
| // internally. | |
| InkTextId GetTextIdAndAdvance(); | |
| void ResetIdTo(size_t id); | |
| private: | |
| size_t GetIdAndAdvance(); | |
| // The next available ID. | |
| size_t next_id_ = 0; | |
| }; | |
| struct EraserState { | |
| EraserState(); | |
| EraserState(const EraserState&) = delete; | |
| EraserState& operator=(const EraserState&) = delete; | |
| ~EraserState(); | |
| bool erasing = false; | |
| base::flat_set<int> page_indices_to_update; | |
| // The event position for the last input, similar to what is stored in | |
| // `DrawingStrokeState` for compensating for missed input events. | |
| std::optional<gfx::PointF> input_last_event_position; | |
| // The type of tool used to generate the input. | |
| ink::StrokeInput::ToolType tool_type; | |
| }; | |
| struct TextHighlightState { | |
| TextHighlightState(); | |
| TextHighlightState(const TextHighlightState&) = delete; | |
| TextHighlightState& operator=(const TextHighlightState&) = delete; | |
| ~TextHighlightState(); | |
| // Tracks whether the current text highlight has finished highlighting a | |
| // multi-click text selection, but has not yet exited text highlight state. | |
| // For example, the user may click text three times to select the line, but | |
| // may not have performed mouseup nor touchend. The user should still be in | |
| // text highlight state but should be unable to highlight any additional | |
| // text. | |
| bool finished_multi_click = false; | |
| // A mapping of 0-based page indices to a list of strokes on pages that | |
| // represent the user's highlighter text selections. Unlike drawing strokes | |
| // which are limited to one page, text selection may cover multiple pages. | |
| // For example, when the user has the highlighter brush selected, they may | |
| // select text from page A to page B. Strokes will be drawn to cover any | |
| // selected text and stored in the page index of the page they are on. | |
| std::map<int, std::vector<ink::Stroke>> highlight_strokes; | |
| // Details from the last input. Used to compensate for missed events, such | |
| // as a missed move event, or an end event that was consumed by a different | |
| // view and detected afterwards when PdfInkModule finally sees input events | |
| // again. Not wrapped in an `std::optional` because this state is only | |
| // active when the user is actively selecting text. The event time is | |
| // unused. | |
| EventDetails input_last_event; | |
| // Whether the text highlight was initiated by a keyboard event. | |
| bool initiated_by_keyboard = false; | |
| }; | |
| // Drawing brush state changes that are pending the completion of an | |
| // in-progress stroke. | |
| struct PendingDrawingBrushState { | |
| SkColor color; | |
| float size; | |
| PdfInkBrush::Type type; | |
| }; | |
| // Data used to draw a text highlight stroke. If `first_point` equals | |
| // `second_point`, then `second_point` is not used. | |
| // `brush_size` should cover the stroke on the smaller dimension of the | |
| // highlight rect. | |
| // All values are based on canonical coordinates. | |
| struct TextSelectionHighlightStrokeData { | |
| gfx::PointF first_point; | |
| gfx::PointF second_point; | |
| float brush_size; | |
| }; | |
| // The transform to and clip page rect needed to render strokes on screen. | |
| struct TransformAndClipRect { | |
| ink::AffineTransform transform; | |
| SkRect clip_rect; | |
| }; | |
| // Event handlers. Returns whether the event was handled or not. | |
| bool OnKeyDown(const blink::WebKeyboardEvent& event); | |
| bool OnMouseDown(const blink::WebMouseEvent& event); | |
| bool OnMouseMove(const blink::WebMouseEvent& event); | |
| bool OnMouseUp(const blink::WebMouseEvent& event); | |
| bool OnTouchStart(const blink::WebTouchEvent& event); | |
| bool OnTouchMove(const blink::WebTouchEvent& event); | |
| bool OnTouchEnd(const blink::WebTouchEvent& event); | |
| // Dedicated handlers for eraser tip events from stylus devices. | |
| bool OnEraserTipTouchStart(const blink::WebTouchEvent& event); | |
| bool OnEraserTipTouchMove(const blink::WebTouchEvent& event); | |
| bool OnEraserTipTouchEnd(const blink::WebTouchEvent& event); | |
| // Helper for event handlers above that deals with potentially missing events. | |
| // Can only be called when is_drawing_stroke() returns true. | |
| void MaybeFinishStrokeForMissingMouseUpEvent(); | |
| // Return values have the same semantics as On{Mouse,Touch}*() above. | |
| bool StartStroke(const gfx::PointF& position, | |
| base::TimeTicks timestamp, | |
| ink::StrokeInput::ToolType tool_type, | |
| const blink::WebPointerProperties* properties); | |
| bool ContinueStroke(const gfx::PointF& position, | |
| base::TimeTicks timestamp, | |
| ink::StrokeInput::ToolType tool_type, | |
| const blink::WebPointerProperties* properties); | |
| bool FinishStroke(const gfx::PointF& position, | |
| base::TimeTicks timestamp, | |
| ink::StrokeInput::ToolType tool_type, | |
| const blink::WebPointerProperties* properties); | |
| // Return values have the same semantics as On{Mouse,Touch}*() above. | |
| bool StartEraseStroke(const gfx::PointF& position, | |
| ink::StrokeInput::ToolType tool_type); | |
| bool ContinueEraseStroke(const gfx::PointF& position, | |
| ink::StrokeInput::ToolType tool_type); | |
| bool FinishEraseStroke(const gfx::PointF& position, | |
| ink::StrokeInput::ToolType tool_type); | |
| // Shared code for the Erase methods above. | |
| void EraseHelper(const gfx::PointF& position, int page_index); | |
| // Return values have the same semantics as On{Mouse,Touch}*() above. | |
| bool StartTextHighlight(const gfx::PointF& position, | |
| int click_count, | |
| ink::StrokeInput::ToolType tool_type); | |
| bool ContinueTextHighlight(const gfx::PointF& position); | |
| bool FinishTextHighlight(const gfx::PointF& position, | |
| bool is_multi_click, | |
| ink::StrokeInput::ToolType tool_type); | |
| // Returns a highlighter stroke that matches the position and size of | |
| // `selection_rect`. `selection_rect` is in canonical coordinates. | |
| // On failure, return std::nullopt. | |
| std::optional<ink::Stroke> GetHighlightStrokeFromSelectionRect( | |
| const gfx::RectF& selection_rect); | |
| // Returns the data needed to create a text highlight stroke that covers | |
| // `selection_rect`. `selection_rect` is in canonical coordinates. | |
| TextSelectionHighlightStrokeData GetTextSelectionHighlightStrokeData( | |
| const gfx::RectF& selection_rect); | |
| // Converts PdfInkModuleClient's text selection to strokes and returns a | |
| // mapping of 0-based page indices to a list of those strokes. See comments | |
| // for `TextHighlightState::highlight_strokes`. | |
| std::map<int, std::vector<ink::Stroke>> GetTextSelectionAsStrokes(); | |
| // Starts a timer for text selection multi-clicks that, when fired, will | |
| // report text highlight metrics. | |
| void StartTextSelectionMultiClickTimer(ink::StrokeInput::ToolType tool_type); | |
| // Stops the timer from `StartTextSelectionMultiClickTimer()` without | |
| // reporting any metrics. | |
| void StopTextSelectionMultiClickTimer(); | |
| // Sets `using_stylus_instead_of_touch_` to true if `tool_type` is | |
| // `ink::StrokeInput::ToolType::kStylus`. Otherwise do nothing. | |
| void MaybeRecordPenInput(ink::StrokeInput::ToolType tool_type); | |
| // Returns true if `using_stylus_instead_of_touch_` is set, and `tool_type` is | |
| // `ink::StrokeInput::ToolType::kTouch`. | |
| bool ShouldIgnoreTouchInput(ink::StrokeInput::ToolType tool_type); | |
| void HandleAnnotationRedoMessage(const base::DictValue& message); | |
| void HandleAnnotationUndoMessage(const base::DictValue& message); | |
| void HandleDeleteTextAnnotationMessage(const base::DictValue& message); | |
| void HandleEditTextAnnotationMessage(const base::DictValue& message); | |
| void HandleFinishTextAnnotationMessage(const base::DictValue& message); | |
| void HandleGetAllTextAnnotationsMessage(const base::DictValue& message); | |
| void HandleGetAnnotationBrushMessage(const base::DictValue& message); | |
| void HandleSetAnnotationBrushMessage(const base::DictValue& message); | |
| void HandleSetAnnotationModeMessage(const base::DictValue& message); | |
| bool is_drawing_stroke() const { | |
| return std::holds_alternative<DrawingStrokeState>(current_tool_state_); | |
| } | |
| bool is_erasing_stroke() const { | |
| return std::holds_alternative<EraserState>(current_tool_state_); | |
| } | |
| bool is_text_highlighting() const { | |
| return std::holds_alternative<TextHighlightState>(current_tool_state_); | |
| } | |
| const DrawingStrokeState& drawing_stroke_state() const { | |
| return std::get<DrawingStrokeState>(current_tool_state_); | |
| } | |
| DrawingStrokeState& drawing_stroke_state() { | |
| return std::get<DrawingStrokeState>(current_tool_state_); | |
| } | |
| const EraserState& erasing_stroke_state() const { | |
| return std::get<EraserState>(current_tool_state_); | |
| } | |
| EraserState& erasing_stroke_state() { | |
| return std::get<EraserState>(current_tool_state_); | |
| } | |
| const TextHighlightState& text_highlight_state() const { | |
| return std::get<TextHighlightState>(current_tool_state_); | |
| } | |
| TextHighlightState& text_highlight_state() { | |
| return std::get<TextHighlightState>(current_tool_state_); | |
| } | |
| // Returns true when the user is using a highlighter over selectable text at | |
| // `position`. Can only be called when is_drawing_stroke() returns true. | |
| // | |
| // - Only returns true when the text highlighting feature is enabled. | |
| bool IsHighlightingTextAtPosition(const gfx::PointF& position) const; | |
| // Returns the current brush. Must be in a drawing stroke state. | |
| PdfInkBrush& GetDrawingBrush(); | |
| const PdfInkBrush& GetDrawingBrush() const; | |
| // Returns the brush with type `brush_type`. | |
| const PdfInkBrush& GetBrush(PdfInkBrush::Type brush_type) const; | |
| // Wrapper around GetEventToCanonicalTransform(). `page_index` is the page | |
| // that the to-be-transformed position is on. The page must be visible. | |
| gfx::Transform GetEventToCanonicalTransformForPage(int page_index); | |
| // Inverse of GetEventToCanonicalTransformForPage(), for convenience. | |
| gfx::Transform GetCanonicalToEventTransformForPage(int page_index); | |
| // Helper to convert `position` to a canonical position and record it into | |
| // `current_tool_state_` for the indicated `timestamp`, `tool_type`, and | |
| // optional `properties`. | |
| // Can only be called when drawing. Returns whether the operation succeeded or | |
| // not. | |
| bool RecordStrokePosition(const gfx::PointF& position, | |
| base::TimeTicks timestamp, | |
| ink::StrokeInput::ToolType tool_type, | |
| const blink::WebPointerProperties* properties); | |
| void ApplyUndoRedoCommands(const PdfInkUndoRedoModel::Commands& commands); | |
| void ApplyUndoRedoCommandsHelper(const PdfInkUndoRedoModel::IdSet& ids, | |
| bool should_draw); | |
| // Discards annotations with IDs >= `lowest_discard` and resets the ID | |
| // generator so those IDs can be reused. Does nothing if `lowest_discard` is | |
| // nullopt. | |
| void ApplyUndoRedoDiscards(std::optional<IdType> lowest_discard); | |
| // Removes the text annotation with `frontend_id`, if it exists. Returns | |
| // the ID of the removed annotation, or std::nullopt if it does not exist. | |
| std::optional<TextId> MaybeDeleteExistingTextAnnotation(int frontend_id); | |
| // Sets the cursor to a drawing/erasing brush cursor when necessary. | |
| void MaybeSetCursor(); | |
| // Handles setting the cursor only for mousemove events at `position`. This | |
| // differs from `MaybeSetCursor()` in that it may also set the cursor to an | |
| // I-beam for text highlighting. | |
| void MaybeSetCursorOnMouseMove(const gfx::PointF& position); | |
| // Returns whether the drawing brush was set or not. | |
| bool MaybeSetDrawingBrush(); | |
| // Returns whether there are any active brush/highlighter strokes in the | |
| // document, including shapes loaded from the PDF. | |
| bool HasStrokes() const; | |
| // Returns the transform and the clip page rect needed to render strokes on | |
| // page `page_index`. | |
| TransformAndClipRect GetTransformAndClipRect(int page_index); | |
| // Updates the page indices in `page_indices` using | |
| // PdfInkModuleClient::RequestThumbnail(). | |
| void RequestThumbnailUpdates(const base::flat_set<int>& page_indices); | |
| // Handles the callback for PDF thumbnail generation requests. Sends | |
| // `thumbnail` to the WebUI. | |
| void OnGotThumbnail(int page_index, Thumbnail thumbnail); | |
| const raw_ref<PdfInkModuleClient> client_; | |
| InkAnnotationMode mode_ = InkAnnotationMode::kOff; | |
| bool using_stylus_instead_of_touch_ = false; | |
| bool loaded_data_from_pdf_ = false; | |
| // Shapes loaded from the PDF. | |
| DocumentV2InkPathShapesMap loaded_v2_shapes_; | |
| // Generates InkStrokeIds and InkTextIds for use in FinishedStrokeState and | |
| // PdfInkUndoRedoModel. | |
| IdGenerator id_generator_; | |
| // Store a PdfInkBrush for each brush type so that the brush parameters are | |
| // saved when swapping between brushes. The PdfInkBrushes should not be | |
| // modified in the middle of an in-progress stroke. | |
| PdfInkBrush highlighter_brush_; | |
| PdfInkBrush pen_brush_; | |
| // The parameters that are to be applied to the drawing brushes when a new | |
| // stroke is started. These can be modified at any time, including in the | |
| // middle of an in-progress stroke. | |
| std::optional<PendingDrawingBrushState> pending_drawing_brush_state_; | |
| // The state of the current tool that is in use. | |
| std::variant<DrawingStrokeState, EraserState, TextHighlightState> | |
| current_tool_state_; | |
| // Brush type to restore after eraser tip interaction ends. | |
| std::optional<PdfInkBrush::Type> saved_brush_type_for_eraser_tip_; | |
| // The state of the strokes that have been completed. | |
| DocumentStrokesMap strokes_; | |
| PdfInkUndoRedoModel undo_redo_model_; | |
| // A timer used for reporting metrics during multi-click text selection. | |
| base::OneShotTimer text_selection_click_timer_; | |
| // Key: Frontend text annotation ID. | |
| // Value: Backend text annotation ID. | |
| std::map<int, TextId> text_id_map_; | |
| // The baseline `text_id_map_` size, initially based on the text annotations | |
| // loaded from the PDF, or std::nullopt if text annotations never got loaded. | |
| // Updated after each save operation. | |
| std::optional<size_t> baseline_text_annotation_count_; | |
| const std::unique_ptr<PdfInkSignatureCreationHandler> | |
| signature_creation_handler_; | |
| base::WeakPtrFactory<PdfInkModule> weak_factory_{this}; | |
| }; | |
| } // namespace chrome_pdf | |
| #endif // PDF_PDF_INK_MODULE_H_ |