layout/docs/AccessibleCaret.rst

   1 ***************
   2 AccessibleCaret
   3 ***************
   4
   5 AccessibleCaret is a pair of raindrop shape handles at both ends of selection
   6 highlight, or it is a single handle at the blinking caret in a text area. It
   7 assists the user to change the range of the selection highlight or the position
   8 of the blinking caret on platforms with touch-event support.
   9
  10
  11 Meta Bug
  12 ========
  13
  14 `Bug 1124074 <https://bugzilla.mozilla.org/show_bug.cgi?id=1124074>`__ tracks all the open issues.
  15
  16
  17 Gecko implementation details
  18 ============================
  19
  20 Preferences
  21 -----------
  22 * ``layout.accessiblecaret.enabled_on_touch`` (Enabled on Firefox with touch-event support since 51.)
  23 * ``layout.accessiblecaret.enabled`` (Defaults off, but it can be turn on to force enable AccessibleCaret.)
  24 * ``layout.accessiblecaret.hide_carets_for_mouse_input`` (Defaults on. Turn
  25   this on to debug AccessibleCaret on desktop browser with mouse events.)
  26
  27 AccessibleCaretEventHub State Transition Diagram
  28 ------------------------------------------------
  29
  30 This diagram depicts the state transition of the state machine in
  31 AccessibleCaretEventHub, which handles external events and callbacks.
  32
  33 Note that the diagram omits some callbacks which do not cause a state transition
  34 such as ``NotifySelectionChanged`` or ``Reflow``.
  35
  36 This table is a mapping of the real events and callback to the actions described
  37 on the edge of the diagram:
  38
  39 +---------------------------------------------------+--------------+
  40 | Real events or callbacks                          | Actions      |
  41 +===================================================+==============+
  42 | ``eMouseDown`` or ``eTouchStart``                 | Press        |
  43 +---------------------------------------------------+--------------+
  44 | ``eMouseMove`` or ``eTouchMove``                  | Move         |
  45 +---------------------------------------------------+--------------+
  46 | ``eMouseUp`` or ``eTouchEnd`` or ``eTouchCancel`` | Release      |
  47 +---------------------------------------------------+--------------+
  48 | ``eMouseLongTap``                                 | Long tap     |
  49 +---------------------------------------------------+--------------+
  50 | ``AsyncPanZoomStarted()``                         | Scroll start |
  51 +---------------------------------------------------+--------------+
  52 | ``AsyncPanZoomStopped()``                         | Scroll end   |
  53 +---------------------------------------------------+--------------+
  54 | ``NotifyBlur()``                                  | Blur         |
  55 +---------------------------------------------------+--------------+
  56
  57 .. image:: AccessibleCaretEventHubStates.png
  58
  59 Debug Tips
  60 ----------
  61
  62 * Dump AccessibleCaret log from command line: run ``MOZ_LOG=AccessibleCaret:5 ./mach run``.
  63 * Dump AccessibleCaret log by using a preference: Open ``about:config`` and add a pref ``logging.AccessibleCaret`` with value ``debug`` or ``verbose`` (case matters).
  64 * ``AC_LOG()`` is useful to add new logs.
  65
  66
  67 Developers
  68 ==========
  69
  70 Current maintainer
  71 ------------------
  72
  73 * Ting-Yu Lin <aethanyc@gmail.com>
  74
  75 Developers Emeritus
  76 -------------------
  77
  78 * Morris Tseng <mtseng@mozilla.com>
  79 * Jeremy Chen <jeremychen@mozilla.com>
  80 * Boris Chiou <boris@mozilla.com>*