Changes: Updated and clarified theming related documentation of feedbacks

RevBy: Daniel d'Andrada

1 files changed, 8 insertions, 10 deletions

diff --git a/doc/src/theme_structure.dox b/doc/src/theme_structure.dox
index 467fcae2..fd55ffc1 100644
--- a/doc/src/theme_structure.dox
+++ b/doc/src/theme_structure.dox
@@ -176,21 +176,19 @@ TODO: explain more.
 
 \subsection feedbacks Feedbacks
 
-The feedbacks are stored in the subdirectory "feedbacks" next to "style", "svg" etc. on the same directory level in the themes. A directory is associated to each feedback under the subdirectory "feedbacks" whose name is the feedback name. The directory names are case sensitive and follow the icon name conventions of the FreeDesktop project (http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html). Therefore "all names may only contain lowercase letters, numbers, underscore, dash, or period characters. Spaces, colons, slashes, and backslashes are not allowed". If a directory name does not follow these rules then it is ignored. These subdirectories contain the feedback effects which can be played by the backends.
+The feedbacks are stored in the subdirectory "feedbacks" next to "style", "svg" etc. on the same directory level in the themes. A directory is associated to each feedback under the subdirectory "feedbacks" whose name is the feedback name. For example feedback sample files for a common feedback named "press" of theme "base" should be located at directory "/usr/share/themes/base/meegotouch/feedback/press". The directory names are case sensitive and follow the icon name conventions of the FreeDesktop project (http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html). Therefore "all names may only contain lowercase letters, numbers, underscore, dash, or period characters. Spaces, colons, slashes, and backslashes are not allowed". If a directory name does not follow these rules then it is ignored. These subdirectories contain the feedback sample files which can be played by the backends.
 
-The base theme contains a fixed number of feedbacks: press, release, error and cancel. For example, the location of a wav file for the pulseaudio backend when error occurs in the base theme: /usr/share/themes/base/dui/feedbacks/error/audio.wav. It is not possible to add more global feedbacks, but they can be overridden in the application specific part of the base theme and the common as well as the application specific part in the derived themes. New feedbacks can be added only in the application specific part of the base theme and these feedbacks can be overridden in the application specific part of the derived themes.
+The common feedback directory of "base" theme contains all the common feedbacks for MeeGo Touch common components and external libraries. The "base" theme contains all of the common feedbacks. This means that new themes that derive from "base" theme can only override existing feedbacks that are already present in the "base" theme. Any new feedbacks that the derived themes introduce will be ignored.
 
-Pulseaudio backend: It is provided to play audio samples on the device speakers. For the lowest latency in the pulseaudio, the feedback samples must be provided in the native format of the hardware. If you provides very different format then the latency will suffer. The pulseaudio backend supports only wav files so far, the name of the audio file must be audio.wav.
+Application specific feedbacks are placed in the application specific feedback directory in the theme directory structure. Applications can override any existing common feedback in the base theme and can add new feedbacks as well. Any new feedbacks should be placed in the application specific feedback directory of the "base" theme. These feedbacks can be overridden by derived themes but here also derived themes cannot introduce any new feedbacks that are not present in the "base" theme.
 
-Vibra backend: This backend uses the Immersion player to play vibra effects. An Immersion effect file (vibra.ivt) must be placed in the feedback directory.
+Pulseaudio backend: This backend plays audio samples from the device speakers. It is recommended to provide feedback files for this backend in the native format of the audio sink. Files that are not in the native format will be converted to native fromat each time the feedback gets loaded. This assures lowest possible latency when playing the audio effects. The pulseaudio backend supports only wav files and the name of the audio file must be "audio.wav".
 
-When an event happens (e.g. pressing on a button) then all feedback devices will play a sample at the same time (play an audio and vibra effect parallel). If a feedback directory does not contain an effect file for a backend (e.g. vibra.ivt) then there is a fallback mechanism to find a sample for the backend going back on the theme inheritance tree. If a zero sized sample file is placed somewhere in the inheritance tree then the backend is ignored. If it is not possible to load some samples for a specific event (e.g. "press-loud") then it tries to fallback to a generic event name (e.g. "press-loud" -> "press") and load the missing sample(s).
+Vibra backend: This backend uses the Immersion TouchSense player to play vibra effects. A vibration effect file ("vibra.ivt") must be placed in the feedback directory.
 
-The feedbacks can be played on three different global volume levels. This is a global setting of the feedback daemon, but the
-feedbacks should be prepared for. The Pulseaudio backend sets the appropriate playback volume for the audio, nothing should be done here.
-The vibra backend checks the vibra.ivt for three specific timeline effects named "low", "medium" and "high" which refers to
-low, medium and high volume levels. If these timeline effects are not available in the effect file then the fallback logic uses
-the first effect from the file (its type does not matter in this case).
+When an event happens (e.g. pressing on a button) then all feedback devices will play a sample at the same time (play an audio and vibra effect in parallel). If a feedback directory does not contain an effect file for a backend (e.g. "vibra.ivt") then there is a fallback mechanism to find a sample for the backend going back on the theme inheritance tree. One example of theme inheritance for a feedback could be: "base/feedbacks", "inherited1/feedbacks", "inherited2/feedbacks", "base/application/feedbacks", "inherited1/application/feedbacks", "inherited2/application/feedbacks". Here "base/feedbacks" means common feedback directory of "base" theme etc. The last directory in the list is the first place to look for the feedback. If a zero sized sample file (either "audio.wav" or "vibra.ivt") is placed somewhere in the inheritance tree that means that the feedback is not played for the backend that the sample file belongs to. If it is not possible to load some samples for a specific event (e.g. "press-loud") then it tries to fallback to a generic event name (e.g. "press-loud" -> "press") and load the missing sample(s). Please note that the fallback mechanism only works for the text before the first dash ('-'). For example fallback for feedbacks "press-really-loud" and "press-loud" is "press".
+
+The feedbacks can be played on three different global volume levels. This is a global setting of the feedback daemon, but the feedbacks should be prepared for it. The Pulseaudio backend sets the appropriate playback volume for the audio, nothing should be done here. The vibra backend checks the "vibra.ivt" file for three specific timeline effects named "low", "medium" and "high" which refers to low, medium and high levels. If these timeline effects are not available in the effect file then the fallback logic uses the first effect from the file (its type does not matter in this case).
 
 \subsection locale Locales Directory