JUCE/extras/BLOCKS/doxygen/pages/juce_getting_touch_events.dox

/**
@page getting_touch_events Getting touch events

Touch events are communicated from BLOCKS devices to your application code via TouchSurface objects.

You can obtain a pointer to the %TouchSurface associated with a specific BLOCKS device from its corresponding Block object using the Block::getTouchSurface() method --- see the @ref discovering_blocks page for an example of how to obtain %Block objects.
For devices without a touch surface (such as the Control %Block) this method will return @s_code{nullptr}, but if the device is capable of sending touch events then the pointer to the %TouchSurface will be valid for the lifetime of the %Block object.

Once you have a %TouchSurface you must register as a TouchSurface::Listener to get touch events.
The process for doing this is to have one of your application's classes inherit from %TouchSurface::Listener and override the pure virtual method TouchSurface::Listener::touchChanged().
Then, when you register your derived class as a listener to a particular %TouchSurface, your overriden method will be called when the corresponding device is touched.

A safe way of registering a class derived from %TouchSurface::Listener with a %TouchSurface is as follows.

@code{.cpp}
class TouchSurfaceListenerExample : public TouchSurface::Listener
{
public:
    TouchSurfaceListenerExample (Block& block)
    {
        if (auto touchSurface = block.getTouchSurface())
            touchSurface->addListener (this);
    }

    void touchChanged (TouchSurface& sourceTouchSurface, const TouchSurface::Touch& touchEvent) override
    {
        // Do something with touchEvent here!
    }
};
@endcode

When your overriden @s_projcode{touchChanged()} method is called you have access to two parameters: a reference to the %TouchSurface that generated this event and a reference to a TouchSurface::Touch.
The %TouchSurface::Touch class contains member variables describing the position, pressure, velocity, timestamp and more.

@section getting_touch_events_example_usage Example usage

To add this functionality to the BlockFinder example project, add %TouchSurface::Listener as a base class to the BlockFinder class and override the @s_projcode{touchChanged()} function as follows:

@code{.cpp}
class BlockFinder : private TopologySource::Listener,
                    private TouchSurface::Listener
{
//...
private:
    //...
    void touchChanged (TouchSurface& sourceTouchSurface, const TouchSurface::Touch& touchEvent) override
    {
        Logger::writeToLog ("Touch Changed!");
    }
    //...
};
@endcode

Then in the @s_projcode{topologyChanged()} callback, add the BlockFinder class as a listener to the connected Blocks in the current topology to receive touch change callbacks as shown below:

@code{.cpp}
void topologyChanged() override
{
    //...
    for (auto& block : currentTopology.blocks)
    {
        //...
        if (auto touchSurface = block->getTouchSurface())
            touchSurface->addListener (this);
    }
}
@endcode

If you run the application now and connect a Lightpad, you should see text in the logger whenever the surface is touched.

You can also find multiple examples of using TouchSurfaces in the @ref example_applications pages.

Learn more about other Block methods from the following pages:

@ref getting_control_button_events

@ref controlling_led_grids

@ref controlling_led_strips

@ref controlling_control_buttons
*/