1 files changed, 51 insertions, 0 deletions
diff --git a/plugins/media-keys/README.media-keys-API b/plugins/media-keys/README.media-keys-API
new file mode 100644
index 0000000..55d1a59
--- /dev/null
+++ b/plugins/media-keys/README.media-keys-API
@@ -0,0 +1,51 @@
+This is very simple documentation to gnome-settings-daemon's
+D-Bus API for media players.
+
+gnome-settings-daemon will send key press events from multimedia
+keys to applications that register their interest in those events.
+This allows the play/pause button to control an audio player that's
+not focused for example.
+
+The D-Bus API is described in gsd-media-keys-manager.c (look for
+introspection_xml), but a small explanation follows here.
+
+1. Create yourself a proxy object for the remote interface:
+Object path: /org/gnome/SettingsDaemon/MediaKeys
+D-Bus name: org.gnome.SettingsDaemon.MediaKeys
+Interface name: org.gnome.SettingsDaemon.MediaKeys
+
+2. Register your application with gnome-settings-daemon
+GrabMediaPlayerKeys ("my-application", 0)
+with the second argument being the current time (usually 0,
+or the time passed to you from an event, such as a mouse click)
+
+3. Listen to the MediaPlayerKeyPressed() signal
+
+4. When receiving a MediaPlayerKeyPressed() signal,
+check whether the first argument (application) matches
+the value you passed to GrabMediaPlayerKeys() and apply the
+action depending on the key (2nd argument)
+
+Possible values of key are:
+- Play
+- Pause
+- Stop
+- Previous
+- Next
+- Rewind
+- FastForward
+- Repeat
+- Shuffle
+
+5. Every time your application is focused, you should call
+GrabMediaPlayerKeys() again, so that gnome-settings-daemon knows
+which one was last used. This allows switching between a movie player
+and a music player, for example, and have the buttons control the
+last used application.
+
+6. When your application wants to stop using the functionality
+it can call ReleaseMediaPlayerKeys(). If your application does
+not call ReleaseMediaPlayerKeys() and releases its D-Bus connection
+then the application will be automatically removed from the list of
+applications held by gnome-settings-daemon.
+