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