1 /*
2   ==============================================================================
3 
4    This file is part of the JUCE library.
5    Copyright (c) 2020 - Raw Material Software Limited
6 
7    JUCE is an open source library subject to commercial or open-source
8    licensing.
9 
10    The code included in this file is provided under the terms of the ISC license
11    http://www.isc.org/downloads/software-support-policy/isc-license. Permission
12    To use, copy, modify, and/or distribute this software for any purpose with or
13    without fee is hereby granted provided that the above copyright notice and
14    this permission notice appear in all copies.
15 
16    JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
17    EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
18    DISCLAIMED.
19 
20   ==============================================================================
21 */
22 
23 namespace juce
24 {
25 
26 /**
27     Represents the touch surface of a BLOCKS device.
28 
29     @tags{Blocks}
30 */
31 class TouchSurface
32 {
33 public:
34     TouchSurface (Block&);
35 
36     /** Destructor. */
37     virtual ~TouchSurface();
38 
39     //==============================================================================
40     /** Structure used to describe touch properties */
41     struct Touch
42     {
43         /** A touch index, which will stay constant for each finger as it is tracked. */
44         int index;
45 
46         /** The X position of this touch on the device, in logical units starting from 0 (left).
47 
48             See Block::getWidth() for the maximum X value on the device.
49         */
50         float x;
51 
52         /** An approximation of the velocity at which the X value is changing, measured in
53             units/second. This is intended as a useful hint to help with gesture detection, but
54             may be 0 if the device doesn't provide this data.
55         */
56         float xVelocity;
57 
58         /** The Y position of this touch on the device, in logical units starting from 0 (top).
59 
60             See Block::getHeight() to find the maximum Y on the device.
61         */
62         float y;
63 
64         /** An approximation of the velocity at which the Y value is changing, measured in
65             units/second. This is intended as a useful hint to help with gesture detection, but
66             may be 0 if the device doesn't provide this data.
67         */
68         float yVelocity;
69 
70         /** The current pressure of this touch, in the range 0.0 (no pressure) to 1.0 (very hard). */
71         float z;
72 
73         /** The rate at which pressure is currently changing, measured in units/second. This is
74             intended as a useful hint to help with gesture detection, but may be 0 if the device
75             doesn't provide this data.
76         */
77         float zVelocity;
78 
79         /** The timestamp of this event, in milliseconds since the device was booted. */
80         Block::Timestamp eventTimestamp;
81 
82         /** True if this is the first event for this finger/index. */
83         bool isTouchStart;
84 
85         /** True if this is the final event as this finger/index is lifted off. */
86         bool isTouchEnd;
87 
88         /** The ID of the block that generated this touch. */
89         Block::UID blockUID;
90 
91         /** The initial X position of the touchStart event corresponding to this finger/index. */
92         float startX;
93 
94         /** The initial Y position of the touchStart event corresponding to this finger/index. */
95         float startY;
96     };
97 
98     //==============================================================================
99     /** Forces a touch-off message for all active touches. */
100     virtual void cancelAllActiveTouches() noexcept = 0;
101 
102     /** For the on-screen seaboard view, this will return the number of keys.
103         For other types of touch-surface, it will return 0. */
104     virtual int getNumberOfKeywaves() const = 0;
105 
106     //==============================================================================
107     /** Receives callbacks when a touch moves or changes pressure. */
108     struct Listener
109     {
110         virtual ~Listener();
111 
112         virtual void touchChanged (TouchSurface&, const Touch&) = 0;
113     };
114 
115     /** Testing feature: this allows you to inject touches onto a touch surface. */
callListenersTouchChanged(const TouchSurface::Touch & t)116     void callListenersTouchChanged (const TouchSurface::Touch& t)
117     {
118         listeners.call ([this, &t] (Listener& l) { l.touchChanged (*this, t); });
119     }
120 
121     /** Adds a listener to be called when the surface is touched. */
122     void addListener (Listener*);
123 
124     /** Removes a previously-registered listener. */
125     void removeListener (Listener*);
126 
127     //==============================================================================
128     /** The block that owns this touch surface. */
129     Block& block;
130 
131 protected:
132     //==============================================================================
133     ListenerList<Listener> listeners;
134 
135     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (TouchSurface)
136 };
137 
138 } // namespace juce
139