Touchscreen update to explain the new features added (#3405)

Co-authored-by: Keith Burzinski <kbx81x@gmail.com>
Co-authored-by: Clyde Stubbs <2366188+clydebarrow@users.noreply.github.com>

components/touchscreen/ft63x6.rst

@@ -0,0 +1,61 @@
+FT63X6 Touchscreen Controller
+================================
+
+.. seo::
+    :description: Instructions for setting up FT63X6 touchscreen controller with ESPHome
+    :image: wt32-sc01.png
+    :keywords: FT63X6, WT32-SC01
+
+The ``ft63x6`` component allows using the touchscreen controller found in
+`Seeed Studio's WT32-SC01 <https://www.seeedstudio.com/ESP32-Development-board-WT32-SC01-p-4735.html>`__
+with ESPHome.
+The :ref:`I²C <i2c>` is required to be set up in your configuration for this sensor to work.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    esp32:
+      board: m5stack-core2
+      framework:
+        type: arduino
+
+    i2c:
+      sda: GPIO18
+      scl: GPIO19
+      scan: false
+
+    output:
+      - platform: ledc
+        pin: GPIO23
+        id: screen_led
+
+    light:
+      - platform: monochromatic
+        output: screen_led
+        default_transition_length: 0.2s
+        name: 'Backlight'
+        restore_mode: ALWAYS_ON
+
+    touchscreen:
+      - platform: ft63x6
+        interrupt_pin: GPIO39
+        on_touch:
+          - logger.log:
+              format: Touch %d at (%d, %d)
+              args: [touch.id, touch.x, touch.y]
+
+Configuration variables:
+------------------------
+
+- **id** (*Optional*, :ref:`config-id`): Manually set the ID of this touchscreen.
+- **reset_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The reset pin of the controller.
+- **interrupt_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The touch detection pin.
+
+- All other options from :ref:`config-touchscreen`.
+
+See Also
+--------
+
+- :doc:`Touchscreen <index>`
+- :apiref:`ft63x6/ft63x6.h`
+- :ghedit:`Edit`

components/touchscreen/index.rst

@@ -5,7 +5,7 @@ Touchscreen Components
     :description: Instruction for using touchscreen components.
     :image: folder-open.svg
 
-The ``touchscreen`` component holds the base code for most touchscreen components
+The ``touchscreen`` component contains the base code for most touchscreen driver components
 available in ESPHome and is responsible for passing the touch events to
 ``binary_sensors`` with the ``touchscreen`` platform.
 
@@ -19,28 +19,82 @@ Base Touchscreen Configuration
     # Example touchscreen
     touchscreen:
       - platform: ...
+        display: display1
         on_touch:
           then:
             ...
+        on_update:
+          then:
+            ...
+        on_release:
+          then:
+            ...
 
 Configuration variables:
 ************************
+- **display** (*Required*, :ref:`config-id`): The display to use this touchscreen with. This will be provided automatically if only one display is configured on the device.
 
 - **on_touch** (*Optional*, :ref:`Automation <automation>`): An automation to perform
   when the touchscreen is touched. See :ref:`touchscreen-on_touch`.
-- **display** (**Required**, :ref:`config-id`): The display to use. If only one display is
-  available, this can be omitted.
+- **on_update** (*Optional*, :ref:`Automation <automation>`): An automation to perform
+  when the touchscreen is touched. See :ref:`touchscreen-on_update`.
+- **on_release** (*Optional*, :ref:`Automation <automation>`): An automation to perform
+  when the touchscreen is no longer touched. See :ref:`touchscreen-on_release`.
+
+
+.. _touchscreen-touchpoint:
+
+``TouchPoint`` Argument Type
+----------------------------
+
+Both the :ref:`touchscreen-on_touch` and :ref:`touchscreen-on_update` have an argument of the type :apistruct:`touchscreen::TouchPoint` in a
+list (``on_update``) or as an ``optional`` (``on_touch``).
+
+The integer members for the touch positions below are in relation to the display width and height:
+
+- ``x`` and ``y`` are the current position.
+- ``x_last`` and ``y_last`` are the previous position.
+- ``x_first`` and ``y_first`` are the position of the touch when it was first detected.
+- ``x_raw`` and ``y_raw`` are for calibrating the touchscreen in relation of the display. This replaces the properties with the same name in the touchscreen classes.
+
+- ``id`` is a number provided by the touchscreen to uniquely identify the touch on a multi-touch screen.
+- ``state`` indicates the state of the touch. This can be **1**, indicating it is an initial touch, or **2** indicating the touch position has changed/moved.
 
 .. _touchscreen-on_touch:
 
 ``on_touch`` Trigger
 --------------------
 
-This automation will be triggered when the touchscreen detects a touch.
+This automation will be triggered when the touchscreen initially detects a touch on the touchscreen; it will not be fired again until
+all touches (for multi-touch supported drivers) are released.
+
+NOTE: This has changed (from ESPHome 2023.11.6.) To receive continuous updates from touch drags, use :ref:`touchscreen-on_update`.
+
+This trigger provides two arguments named ``touch`` of type *touchpoint* and ``touches`` with a list of all touches.
+
+.. _touchscreen-on_update:
+
+``on_update`` Trigger
+---------------------
+
+This new automation will be triggered when the touchscreen detects an extra touch or that a touch has moved around on the screen.
+
+
+This trigger provides one argument named ``touches`` of type :apiref:`touchscreen::TouchPoints_t` which has a list of
+ :ref:`touchscreen-touchpoint`.
+
+This trigger may be useful to detect gestures such as swiping across the display.
+
+
+.. _touchscreen-on_release:
+
+``on_release`` Trigger
+----------------------
+
+This automation will be triggered when all touches are released from the touchscreen.
+
+At this point of time it has no extra arguments.
 
-This trigger provides one argument named ``touch`` of type :apistruct:`touchscreen::TouchPoint` which has two integer members: ``x`` and ``y`` which
-represent the position of the touch in relation to the display width and height. It also has optional members that will be set
-depending on the touchscreen platform.
 
 Binary Sensor
 -------------

components/touchscreen/xpt2046.rst

@@ -108,10 +108,10 @@ values nor ``swap_x_y``.
       on_touch:
         - lambda: |-
               ESP_LOGI("cal", "x=%d, y=%d, x_raw=%d, y_raw=%0d",
-                  id(my_touchscreen).x,
-                  id(my_touchscreen).y,
-                  id(my_touchscreen).x_raw,
-                  id(my_touchscreen).y_raw
+                  touch.x,
+                  touch.y,
+                  touch.x_raw,
+                  touch.y_raw
                   );
 
 Get a stylus or a similar object, run the project and touch the corners of the screen at
@@ -175,9 +175,9 @@ using a display lambda similar to the following.
     display:
       - platform: ili9341
         lambda: |-
-          it.fill(BLACK);
-          if (id(my_touchscreen).touched)
-            it.filled_circle(id(my_touchscreen).x, id(my_touchscreen).y, 10, RED);
+          auto touch = id(my_touchscreen)->get_touch();
+          if (touch) // or touch.has_value()
+            it.filled_circle(touch.value().x, touch.value().y, 10, RED);
 
 To be exact, the component does the following
 

index.rst

@@ -680,10 +680,10 @@ Touchscreen Components
     EKTF2232, components/touchscreen/ektf2232, ektf2232.svg, Inkplate 6 Plus
     Lilygo T5 4.7", components/touchscreen/lilygo_t5_47, lilygo_t5_47_touch.jpg
     TT21100, components/touchscreen/tt21100, esp32-s3-korvo-2-lcd.png
-    GT911, components/touchscreen/gt911, esp32_s3_box_3.png
     XPT2046, components/touchscreen/xpt2046, xpt2046.jpg
-
-
+    GT911, components/touchscreen/gt911, esp32_s3_box_3.png
+    FT63X6, components/touchscreen/ft63x6, wt32-sc01.png
+    
 Cover Components
 ----------------