1 /*
2  * Copyright (C) 2024 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package com.google.android.msdl.data.model
18 
19 /** System-level tokens defined in the Multi-sensory Design Language (MSDL) */
20 enum class MSDLToken(
21     val hapticToken: HapticToken,
22     val soundToken: SoundToken,
23     val minimumFeedbackLevel: FeedbackLevel,
24 ) {
25     /* Inform the user with emphasis that their current action FAILED to complete */
26     FAILURE_HIGH_EMPHASIS(
27         HapticToken.NEGATIVE_CONFIRMATION_HIGH_EMPHASIS,
28         SoundToken.FAILURE_HIGH_EMPHASIS,
29         FeedbackLevel.MINIMAL,
30     ),
31     /* Inform the user that their current action FAILED to complete */
32     FAILURE(
33         HapticToken.NEGATIVE_CONFIRMATION_MEDIUM_EMPHASIS,
34         SoundToken.FAILURE,
35         FeedbackLevel.MINIMAL,
36     ),
37     /* Inform the user their current action was completed SUCCESSFULLY */
38     SUCCESS(
39         HapticToken.POSITIVE_CONFIRMATION_HIGH_EMPHASIS,
40         SoundToken.SUCCESS,
41         FeedbackLevel.MINIMAL,
42     ),
43     /* Inform the user that an ongoing activity has started */
44     START(HapticToken.NEUTRAL_CONFIRMATION_HIGH_EMPHASIS, SoundToken.START, FeedbackLevel.DEFAULT),
45     /* Inform the user that an ongoing activity has paused */
46     PAUSE(
47         HapticToken.NEUTRAL_CONFIRMATION_MEDIUM_EMPHASIS,
48         SoundToken.PAUSE,
49         FeedbackLevel.DEFAULT,
50     ),
51     /* Inform the user that their previously started activity has stopped SUCCESSFULLY */
52     STOP(HapticToken.POSITIVE_CONFIRMATION_MEDIUM_EMPHASIS, SoundToken.STOP, FeedbackLevel.DEFAULT),
53     /* Inform the user that their previously started activity has cancelled SUCCESSFULLY */
54     CANCEL(
55         HapticToken.POSITIVE_CONFIRMATION_MEDIUM_EMPHASIS,
56         SoundToken.CANCEL,
57         FeedbackLevel.DEFAULT,
58     ),
59     /* Inform the user that the state of an interactive component has been switched to on SUCCESSFULLY */
60     SWITCH_ON(
61         HapticToken.POSITIVE_CONFIRMATION_MEDIUM_EMPHASIS,
62         SoundToken.SWITCH_ON,
63         FeedbackLevel.DEFAULT,
64     ),
65     /* Inform the user that the state of an interactive component has been switched to off SUCCESSFULLY */
66     SWITCH_OFF(
67         HapticToken.POSITIVE_CONFIRMATION_MEDIUM_EMPHASIS,
68         SoundToken.SWITCH_OFF,
69         FeedbackLevel.DEFAULT,
70     ),
71     /* Inform the user the state of their device changed to unlocked SUCCESSFULLY */
72     UNLOCK(
73         HapticToken.POSITIVE_CONFIRMATION_LOW_EMPHASIS,
74         SoundToken.UNLOCK,
75         FeedbackLevel.DEFAULT,
76     ),
77     /* Inform the user the state of their device changed to locked SUCCESSFULLY */
78     LOCK(HapticToken.POSITIVE_CONFIRMATION_LOW_EMPHASIS, SoundToken.LOCK, FeedbackLevel.DEFAULT),
79     /* Inform the user that their long-press gesture has resulted in the revealing of more contextual information */
80     LONG_PRESS(HapticToken.LONG_PRESS, SoundToken.LONG_PRESS, FeedbackLevel.MINIMAL),
81     /* Inform the user that their swipe gesture has reached a threshold that confirms navigation or the reveal of additional information. */
82     SWIPE_THRESHOLD_INDICATOR(
83         HapticToken.SWIPE_THRESHOLD_INDICATOR,
84         SoundToken.SWIPE_THRESHOLD_INDICATOR,
85         FeedbackLevel.MINIMAL,
86     ),
87     /* Played when the user taps on a high-emphasis UI element */
88     TAP_HIGH_EMPHASIS(
89         HapticToken.TAP_HIGH_EMPHASIS,
90         SoundToken.TAP_HIGH_EMPHASIS,
91         FeedbackLevel.EXPRESSIVE,
92     ),
93     /* Inform the user that their tap has resulted in a selection */
94     TAP_MEDIUM_EMPHASIS(
95         HapticToken.TAP_MEDIUM_EMPHASIS,
96         SoundToken.TAP_MEDIUM_EMPHASIS,
97         FeedbackLevel.DEFAULT,
98     ),
99     /* Played when a users drag gesture reaches the maximum or minimum value */
100     DRAG_THRESHOLD_INDICATOR_LIMIT(
101         HapticToken.DRAG_THRESHOLD_INDICATOR,
102         SoundToken.DRAG_THRESHOLD_INDICATOR_LIMIT,
103         FeedbackLevel.DEFAULT,
104     ),
105     /* Inform the user that their drag gesture has resulted in an incremental value change.
106      * For usage in haptic sliders that change continuously, this token can be played along with
107      * [InteractionProperties.DynamicVibrationScale] properties to control haptic scaling as a
108      * function of position and velocity.
109      */
110     DRAG_INDICATOR_CONTINUOUS(
111         HapticToken.DRAG_INDICATOR_CONTINUOUS,
112         SoundToken.NO_SOUND,
113         FeedbackLevel.DEFAULT,
114     ),
115     /* Inform the user that their drag gesture has resulted in a stepped value change.
116      * For usage in haptic sliders that change in discrete steps, this token can be played with
117      * [InteractionProperties.DynamicVibrationScale] properties to control haptic scaling as a
118      * function of position and velocity.
119      */
120     DRAG_INDICATOR_DISCRETE(
121         HapticToken.DRAG_INDICATOR_DISCRETE,
122         SoundToken.DRAG_INDICATOR,
123         FeedbackLevel.DEFAULT,
124     ),
125     /* Played when a user taps on any UI element that can be interacted with but is not otherwise defined */
126     TAP_LOW_EMPHASIS(
127         HapticToken.TAP_LOW_EMPHASIS,
128         SoundToken.TAP_LOW_EMPHASIS,
129         FeedbackLevel.EXPRESSIVE,
130     ),
131     /* Played when the user touches a key on the keyboard that is otherwise undefined */
132     KEYPRESS_STANDARD(
133         HapticToken.KEYPRESS_STANDARD,
134         SoundToken.KEYPRESS_STANDARD,
135         FeedbackLevel.DEFAULT,
136     ),
137     /* Played when the user touches the space key */
138     KEYPRESS_SPACEBAR(
139         HapticToken.KEYPRESS_SPACEBAR,
140         SoundToken.KEYPRESS_SPACEBAR,
141         FeedbackLevel.DEFAULT,
142     ),
143     /* Played when the user touches the return key */
144     KEYPRESS_RETURN(HapticToken.KEYPRESS_RETURN, SoundToken.KEYPRESS_RETURN, FeedbackLevel.DEFAULT),
145     /* Played when the user touches the delete key */
146     KEYPRESS_DELETE(HapticToken.KEYPRESS_DELETE, SoundToken.KEYPRESS_DELETE, FeedbackLevel.DEFAULT),
147 }
148 
149 /** Level of feedback that contains a token */
150 enum class FeedbackLevel {
151     NO_FEEDBACK,
152     MINIMAL,
153     DEFAULT,
154     EXPRESSIVE,
155 }
156