ui/touch_selection/touch_selection_controller.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef UI_TOUCH_SELECTION_TOUCH_SELECTION_CONTROLLER_H_
   6 #define UI_TOUCH_SELECTION_TOUCH_SELECTION_CONTROLLER_H_
   7
   8 #include "base/time/time.h"
   9 #include "ui/base/touch/selection_bound.h"
  10 #include "ui/gfx/geometry/point_f.h"
  11 #include "ui/gfx/geometry/rect_f.h"
  12 #include "ui/gfx/geometry/vector2d_f.h"
  13 #include "ui/touch_selection/longpress_drag_selector.h"
  14 #include "ui/touch_selection/selection_event_type.h"
  15 #include "ui/touch_selection/touch_handle.h"
  16 #include "ui/touch_selection/touch_handle_orientation.h"
  17 #include "ui/touch_selection/ui_touch_selection_export.h"
  18
  19 namespace ui {
  20 class MotionEvent;
  21
  22 // Interface through which |TouchSelectionController| issues selection-related
  23 // commands, notifications and requests.
  24 class UI_TOUCH_SELECTION_EXPORT TouchSelectionControllerClient {
  25  public:
  26   virtual ~TouchSelectionControllerClient() {}
  27
  28   virtual bool SupportsAnimation() const = 0;
  29   virtual void SetNeedsAnimate() = 0;
  30   virtual void MoveCaret(const gfx::PointF& position) = 0;
  31   virtual void MoveRangeSelectionExtent(const gfx::PointF& extent) = 0;
  32   virtual void SelectBetweenCoordinates(const gfx::PointF& base,
  33                                         const gfx::PointF& extent) = 0;
  34   virtual void OnSelectionEvent(SelectionEventType event) = 0;
  35   virtual scoped_ptr<TouchHandleDrawable> CreateDrawable() = 0;
  36 };
  37
  38 // Controller for manipulating text selection via touch input.
  39 class UI_TOUCH_SELECTION_EXPORT TouchSelectionController
  40     : public TouchHandleClient,
  41       public LongPressDragSelectorClient {
  42  public:
  43   enum ActiveStatus {
  44     INACTIVE,
  45     INSERTION_ACTIVE,
  46     SELECTION_ACTIVE,
  47   };
  48
  49   struct UI_TOUCH_SELECTION_EXPORT Config {
  50     Config();
  51     ~Config();
  52
  53     // Maximum allowed time for handle tap detection. Defaults to 300 ms.
  54     base::TimeDelta max_tap_duration;
  55
  56     // Defaults to 8 DIPs.
  57     float tap_slop;
  58
  59     // Controls whether drag selection after a longpress is enabled.
  60     // Defaults to false.
  61     bool enable_longpress_drag_selection;
  62
  63     // Controls whether an insertion handle is shown on a tap for an empty
  64     // editable text. Defauls to false.
  65     bool show_on_tap_for_empty_editable;
  66   };
  67
  68   TouchSelectionController(TouchSelectionControllerClient* client,
  69                            const Config& config);
  70   ~TouchSelectionController() override;
  71
  72   // To be called when the selection bounds have changed.
  73   // Note that such updates will trigger handle updates only if preceded
  74   // by an appropriate call to allow automatic showing.
  75   void OnSelectionBoundsChanged(const SelectionBound& start,
  76                                 const SelectionBound& end);
  77
  78   // Allows touch-dragging of the handle.
  79   // Returns true iff the event was consumed, in which case the caller should
  80   // cease further handling of the event.
  81   bool WillHandleTouchEvent(const MotionEvent& event);
  82
  83   // To be called before forwarding a tap event. This allows automatically
  84   // showing the insertion handle from subsequent bounds changes.
  85   bool WillHandleTapEvent(const gfx::PointF& location);
  86
  87   // To be called before forwarding a longpress event. This allows automatically
  88   // showing the selection or insertion handles from subsequent bounds changes.
  89   bool WillHandleLongPressEvent(base::TimeTicks event_time,
  90                                 const gfx::PointF& location);
  91
  92   // Allow showing the selection handles from the most recent selection bounds
  93   // update (if valid), or a future valid bounds update.
  94   void AllowShowingFromCurrentSelection();
  95
  96   // Hide the handles and suppress bounds updates until the next explicit
  97   // showing allowance.
  98   void HideAndDisallowShowingAutomatically();
  99
 100   // Override the handle visibility according to |hidden|.
 101   void SetTemporarilyHidden(bool hidden);
 102
 103   // To be called when the editability of the focused region changes.
 104   void OnSelectionEditable(bool editable);
 105
 106   // To be called when the contents of the focused region changes.
 107   void OnSelectionEmpty(bool empty);
 108
 109   // Ticks an active animation, as requested to the client by |SetNeedsAnimate|.
 110   // Returns true if an animation is active and requires further ticking.
 111   bool Animate(base::TimeTicks animate_time);
 112
 113   // Returns the rect between the two active selection bounds. If just one of
 114   // the bounds is visible, the rect is simply the (one-dimensional) rect of
 115   // that bound. If no selection is active, an empty rect will be returned.
 116   gfx::RectF GetRectBetweenBounds() const;
 117
 118   // Returns the visible rect of specified touch handle. For an active insertion
 119   // these values will be identical.
 120   gfx::RectF GetStartHandleRect() const;
 121   gfx::RectF GetEndHandleRect() const;
 122
 123   // Returns the focal point of the start and end bounds, as defined by
 124   // their bottom coordinate.
 125   const gfx::PointF& GetStartPosition() const;
 126   const gfx::PointF& GetEndPosition() const;
 127
 128   const SelectionBound& start() const { return start_; }
 129   const SelectionBound& end() const { return end_; }
 130
 131   ActiveStatus active_status() const { return active_status_; }
 132
 133  private:
 134   friend class TouchSelectionControllerTestApi;
 135
 136   enum InputEventType { TAP, LONG_PRESS, INPUT_EVENT_TYPE_NONE };
 137
 138   // TouchHandleClient implementation.
 139   void OnDragBegin(const TouchSelectionDraggable& draggable,
 140                    const gfx::PointF& drag_position) override;
 141   void OnDragUpdate(const TouchSelectionDraggable& draggable,
 142                     const gfx::PointF& drag_position) override;
 143   void OnDragEnd(const TouchSelectionDraggable& draggable) override;
 144   bool IsWithinTapSlop(const gfx::Vector2dF& delta) const override;
 145   void OnHandleTapped(const TouchHandle& handle) override;
 146   void SetNeedsAnimate() override;
 147   scoped_ptr<TouchHandleDrawable> CreateDrawable() override;
 148   base::TimeDelta GetMaxTapDuration() const override;
 149
 150   // LongPressDragSelectorClient implementation.
 151   void OnLongPressDragActiveStateChanged() override;
 152   gfx::PointF GetSelectionStart() const override;
 153   gfx::PointF GetSelectionEnd() const override;
 154
 155   void ShowInsertionHandleAutomatically();
 156   void ShowSelectionHandlesAutomatically();
 157   bool WillHandleTapOrLongPress(const gfx::PointF& location);
 158
 159   void OnInsertionChanged();
 160   void OnSelectionChanged();
 161
 162   // Returns true if insertion mode was newly (re)activated.
 163   bool ActivateInsertionIfNecessary();
 164   void DeactivateInsertion();
 165   // Returns true if selection mode was newly (re)activated.
 166   bool ActivateSelectionIfNecessary();
 167   void DeactivateSelection();
 168   void ForceNextUpdateIfInactive();
 169
 170   bool WillHandleTouchEventForLongPressDrag(const MotionEvent& event);
 171   void SetTemporarilyHiddenForLongPressDrag(bool hidden);
 172   void RefreshHandleVisibility();
 173
 174   gfx::Vector2dF GetStartLineOffset() const;
 175   gfx::Vector2dF GetEndLineOffset() const;
 176   bool GetStartVisible() const;
 177   bool GetEndVisible() const;
 178   TouchHandle::AnimationStyle GetAnimationStyle(bool was_active) const;
 179
 180   void LogSelectionEnd();
 181
 182   TouchSelectionControllerClient* const client_;
 183   const Config config_;
 184
 185   // Whether to force an update on the next selection event even if the
 186   // cached selection matches the new selection.
 187   bool force_next_update_;
 188
 189   InputEventType response_pending_input_event_;
 190
 191   SelectionBound start_;
 192   SelectionBound end_;
 193   TouchHandleOrientation start_orientation_;
 194   TouchHandleOrientation end_orientation_;
 195
 196   ActiveStatus active_status_;
 197
 198   scoped_ptr<TouchHandle> insertion_handle_;
 199   bool activate_insertion_automatically_;
 200
 201   scoped_ptr<TouchHandle> start_selection_handle_;
 202   scoped_ptr<TouchHandle> end_selection_handle_;
 203   bool activate_selection_automatically_;
 204
 205   bool selection_empty_;
 206   bool selection_editable_;
 207
 208   bool temporarily_hidden_;
 209
 210   // Whether to use the start bound (if false, the end bound) for computing the
 211   // appropriate text line offset when performing a selection drag. This helps
 212   // ensure that the initial selection induced by the drag doesn't "jump"
 213   // between lines.
 214   bool anchor_drag_to_selection_start_;
 215
 216   // Longpress drag allows direct manipulation of longpress-initiated selection.
 217   LongPressDragSelector longpress_drag_selector_;
 218
 219   base::TimeTicks selection_start_time_;
 220   // Whether a selection handle was dragged during the current 'selection
 221   // session' - i.e. since the current selection has been activated.
 222   bool selection_handle_dragged_;
 223
 224   DISALLOW_COPY_AND_ASSIGN(TouchSelectionController);
 225 };
 226
 227 }  // namespace ui
 228
 229 #endif  // UI_TOUCH_SELECTION_TOUCH_SELECTION_CONTROLLER_H_