Event-naming-spec-0.0.0.md 4.65 KB
Newer Older
Guido Gunther's avatar
Guido Gunther committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
This is similar in spirit (and heavily based on) to the [Sound naming spec][].

# Overview

This specification gives direction on how to name the Event types
(triggering feedbacks such as running the haptic motor or blinking an
LED) that are available for use by applications, when creating a
feedback theme. It does so by laying out a standard naming scheme for
Event creation, as well as providing a minimal list of must have
Events, and a larger list with many more examples to help with the
creation of extended Events for third party applications, with
different event types and usage.

# Context

The list of default contexts for the feedback theme are:

- Alerts: Events to alert the user of an action or event which may
  have a major impact on the system or their current use
- Notifications: Events to trigger feedback to notify the user that
  the system, or their current use case has changed state in some way,
  e.g. new email arriving
- Actions:	Event that notify the user on their actions.
- Input Event: This triggers feedbacks that give direct response to
  input events from the user, such as key presses on an on screen
  keyboard

# Event naming guides

Here we define some guidelines for when creating new Event names
that extend the standardized list of Event names defined here, in
order to provide Events for more specific events and usages.

Event names are in the en_US.US_ASCII locale. This means that the
characters allowed in the Event names must fall within the US-ASCII
character set. As a further restriction, all Event names may only
contain lowercase letters, numbers, underscore, dash, or period
characters. Spaces, colons, slashes, and backslashes are not
allowed. Also, sound names must be spelled as they are in the en_US
dictionary.

Events for branded applications should be named the same as the binary
executable for the application, prefixed by the string “x-”, to avoid
name space clashes with future standardized names. Example:
“x-openoffice-foobar”.

## Standard Event names

This section describes the standard Event names that should be used
by artists when creating themes, and by developers when writing
applications which will use the Feedback Theme Specification.

### Alerts

- battery-low: The Event used when the battery is low (below 20%, for example).
- power-unplug-battery-low: The power cable has been unplugged and the battery level is low.

### Notifications

60
61
- camera-focus: The event used when the camera got focus.
- camera-shutter: The event used when a photo was taken.
Guido Gunther's avatar
Guido Gunther committed
62
63
64
- message-new-instant: The event used when a new IM is received.
- message-new-sms:  The event used when a new sms is received.
- message-new-email:  The event used when a new email is received.
65
- message-missed-email: The event used when an email was received but not seen by the user.
Guido Gunther's avatar
Guido Gunther committed
66
- message-missed-instant: The event used when a instant message was received but not seen by the user.
67
- message-missed-notification: The event used when a notification was shown but not seen by the user.
Guido Gunther's avatar
Guido Gunther committed
68
- message-missed-sms: The event used when a sms message was received but not seen by the user.
69
70
- phone-incoming-call: The event used when a phone/voip call is coming in.
- phone-missed-call: The event used when a phone/voip call is was incoming but not answered.
71
72
73
- phone-outgoing-busy: The event used when for outgoing phone/voip call when the responder is busy/not available.
- phone-hangup: The event used when a phone/voip call is hung up.
- phone-failure: The event used when a phone/voip call is terminated because of a failure.
74
- battery-caution: The event used when the battery is nearing exhaustion (below 40%, for example).
Guido Gunther's avatar
Guido Gunther committed
75
76
77
78
79
- battery-full:	The event used when the battery is fully loaded up.
- device-added: The event used when a device has become available to the desktop, i.e. due to USB plugging.
- power-plug: The power cable has been plugged in.
- power-unplug: The power cable has been unplugged.
- alarm-clock-elapsed: A user configured alarm elapsed.
Luca Weiss's avatar
Luca Weiss committed
80
- timeout-completed: A user configured timeout completed (e.g. a stop watch).
Guido Gunther's avatar
Guido Gunther committed
81
82
83
84
85
86
87
88
89
90
91
92

### Actions

- message-sent-instant: The sound used when a new IM is sent.
- bell-terminal: The sound to use as a terminal bell.
- theme-demo: A event that should be played for demoing this theme. Usually
  this should just be an alias for a very representative sound (such as
  a incoming phone call) of a theme that would work nicely as a demo event for
  a theme in the theme selector dialog.

### Input Event

93
94
- button-pressed:	The event used when a button is pressed.
- button-released:  The event used when a button is released.
Guido Gunther's avatar
Guido Gunther committed
95
96
97
- window-close:     The sound used when an existing window is closed.

[Sound naming spec]: http://0pointer.de/public/sound-naming-spec.html