begin documentation updates

README.md

@@ -92,9 +92,17 @@ playerctl status --format "STATUS: {{ uc(status) }}"
 | `duration` | int             | Convert the duration to hh:mm:ss format.                |
 | `emoji`    | status, volume  | Try to convert the variable to an emoji representation. |
 
+### Following changes
+
+You can pass the `--follow` flag to query commands to block, wait for players to connect, and print the query whenever it changes. If players are passed with `--player`, players earlier in the list will be preferred in the order they appear unless `--all-players` is passed. When no player can support the query, such as when all the players exit, a newline will be printed. For example, to be notified of information about the latest currently playing track for your media players, use:
+
+```bash
+playerctl metadata --format '{{ playerName }}: {{ artist }} - {{ title }} {{ duration(position) }}|{{ duration(mpris:length) }}' --follow
+```
+
 ## Using the Library
 
-To use a scripting library, find your favorite language from [this list](https://wiki.gnome.org/Projects/GObjectIntrospection/Users) and install the bindings library. Documentation for the library is hosted [here](https://dubstepdish.com/playerctl).
+To use a scripting library, find your favorite language from [this list](https://wiki.gnome.org/Projects/GObjectIntrospection/Users) and install the bindings library. Documentation for the library is hosted [here](https://dubstepdish.com/playerctl). For examples on how to use the library, see the [examples](https://github.com/acrisci/playerctl/blob/master/examples) folder.
 
 ### Example Python Script
 
@@ -123,9 +131,9 @@ def on_pause(player, status):
     print('Paused the song: {}'.format(player.get_title()))
 
 
-player.on('status::playing', on_play)
-player.on('status::paused', on_pause)
-player.on('metadata', on_metadata)
+player.connect('status::playing', on_play)
+player.connect('status::paused', on_pause)
+player.connect('metadata', on_metadata)
 
 # start playing some music
 player.play()
@@ -139,6 +147,8 @@ main = GLib.MainLoop()
 main.run()
 ```
 
+For a more complete example which is capable of listening to when players start and exit, see [player-manager.py](https://github.com/acrisci/playerctl/blob/master/examples/player-manager.py) from the official examples.
+
 ## Installing
 
 First, check and see if the library is available from your package manager (if it is not, get someone to host a package for you) and also check the [releases](https://github.com/acrisci/playerctl/releases) page on github.

doc/reference/meson.build

@@ -30,6 +30,7 @@ gnome.gtkdoc(
     'playerctl.h',
     'playerctl-generated.h',
     'playerctl-common.h',
+    'playerctl-formatter.h',
   ],
   install: true,
 )

doc/reference/playerctl-docs.xml

@@ -16,8 +16,10 @@
   </bookinfo>
 
   <chapter>
-    <title>Player</title>
+    <title>Playerctl</title>
         <xi:include href="xml/playerctl-player.xml"/>
+        <xi:include href="xml/playerctl-player-manager.xml"/>
+        <xi:include href="xml/playerctl-player-name.xml"/>
 
   </chapter>
   <chapter id="object-tree">

examples/manager.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+
+from gi.repository import Playerctl, GLib
+
+manager = Playerctl.PlayerManager()
+
+def on_play(player, status, manager):
+    print('player is playing: {}'.format(player.props.player_name))
+
+def on_metadata(player, metadata, manager):
+    keys = metadata.keys()
+    if 'xesam:artist' in keys and 'xesam:title' in keys:
+        print('{} - {}'.format(metadata['xesam:artist'][0], metadata['xesam:title']))
+
+def init_player(name):
+    # choose if you want to manage the player based on the name
+    if name.name.startswith('vlc'):
+        player = Playerctl.Player.new_from_name(name)
+        player.connect('playback-status::playing', on_play, manager)
+        player.connect('metadata', on_metadata, manager)
+        manager.manage_player(player)
+
+def on_name_appeared(manager, name):
+    init_player(name)
+
+def on_player_vanished(manager, player):
+    print('player has exited: {}'.format(player.props.player_id))
+
+manager.connect('name-appeared', on_name_appeared)
+manager.connect('player-vanished', on_player_vanished)
+
+for name in manager.props.player_names:
+    init_player(name)
+
+main = GLib.MainLoop()
+main.run()

playerctl/playerctl-cli.c

@@ -917,7 +917,7 @@ static void name_appeared_callback(PlayerctlPlayerManager *manager,
 
     GError *error = NULL;
     PlayerctlPlayer *player =
-        playerctl_player_new_for_name(name, &error);
+        playerctl_player_new_from_name(name, &error);
     if (error != NULL) {
         exit_status = 1;
         g_printerr("Could not connect to player: %s\n", error->message);
@@ -1104,7 +1104,7 @@ int main(int argc, char *argv[]) {
         has_selected = TRUE;
 
         PlayerctlPlayer *player =
-            playerctl_player_new_for_name(name, &error);
+            playerctl_player_new_from_name(name, &error);
         if (error != NULL) {
             g_printerr("Could not connect to player: %s\n", error->message);
             exit_status = 1;

playerctl/playerctl-player-manager.c

@@ -375,6 +375,12 @@ static void playerctl_player_manager_initable_iface_init(GInitableIface *iface)
     iface->init = playerctl_player_manager_initable_init;
 }
 
+/**
+ * playerctl_player_manager_new:
+ * @err: (allow-none): The location of a #GError or %NULL.
+ *
+ * Returns:(transfer full): A new #PlayerctlPlayerManager.
+ */
 PlayerctlPlayerManager *playerctl_player_manager_new(GError **err) {
     GError *tmp_error = NULL;
 

playerctl/playerctl-player-manager.h

@@ -29,7 +29,7 @@
 
 /**
  * SECTION: playerctl-player-manager
- * @short_description: A class watch for player names appearing and vanishing
+ * @short_description: A class to watch for players appearing and vanishing.
  */
 #define PLAYERCTL_TYPE_PLAYER_MANAGER (playerctl_player_manager_get_type())
 #define PLAYERCTL_PLAYER_MANAGER(obj) \

playerctl/playerctl-player-name.h

@@ -23,6 +23,11 @@
 #include <glib.h>
 #include <glib-object.h>
 
+/**
+ * SECTION: playerctl-player-name
+ * @short_description: A box that contains connection information for a player.
+ */
+
 /**
  * PlayerctlSource
  * @PLAYERCTL_SOURCE_NONE: Only for unitialized players. Source will be chosen automatically.

playerctl/playerctl-player.c

@@ -600,7 +600,7 @@ static void playerctl_player_class_init(PlayerctlPlayerClass *klass) {
 
     obj_properties[PROP_METADATA] = g_param_spec_variant(
         "metadata", "Player metadata",
-        "The metadata of the currently playing track", G_VARIANT_TYPE_VARIANT,
+        "The metadata of the currently playing track", g_variant_type_new("a{sv}"),
         NULL, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
 
     obj_properties[PROP_CAN_CONTROL] = g_param_spec_boolean(
@@ -685,7 +685,13 @@ static void playerctl_player_class_init(PlayerctlPlayerClass *klass) {
                      1,                               /* n_params */
                      G_TYPE_BOOLEAN);
 
-    /* DEPRECATED */
+    /**
+     * PlayerctlPlayer::play:
+     *
+     * Emitted when the player begins to play.
+     *
+     * Deprecated: 2.0.0
+     */
     connection_signals[PLAY] =
         g_signal_new("play",                        /* signal_name */
                      PLAYERCTL_TYPE_PLAYER,         /* itype */
@@ -698,7 +704,13 @@ static void playerctl_player_class_init(PlayerctlPlayerClass *klass) {
                      G_TYPE_NONE,                   /* return_type */
                      0);                            /* n_params */
 
-    /* DEPRECATED */
+    /**
+     * PlayerctlPlayer::pause:
+     *
+     * Emitted when the player pauses.
+     *
+     * Deprecated: 2.0.0
+     */
     connection_signals[PAUSE] =
         g_signal_new("pause",                       /* signal_name */
                      PLAYERCTL_TYPE_PLAYER,         /* itype */
@@ -711,7 +723,13 @@ static void playerctl_player_class_init(PlayerctlPlayerClass *klass) {
                      G_TYPE_NONE,                   /* return_type */
                      0);                            /* n_params */
 
-    /* DEPRECATED */
+    /**
+     * PlayerctlPlayer::stop:
+     *
+     * Emitted when the player stops.
+     *
+     * Deprecated: 2.0.0
+     */
     connection_signals[STOP] =
         g_signal_new("stop",                        /* signal_name */
                      PLAYERCTL_TYPE_PLAYER,         /* itype */
@@ -724,6 +742,12 @@ static void playerctl_player_class_init(PlayerctlPlayerClass *klass) {
                      G_TYPE_NONE,                   /* return_type */
                      0);                            /* n_params */
 
+    /**
+     * PlayerctlPlayer:metadata:
+     * @metadata: the metadata for the currently playing track.
+     *
+     * Emitted when the metadata for the currently playing track changes.
+     */
     connection_signals[METADATA] =
         g_signal_new("metadata",                       /* signal_name */
                      PLAYERCTL_TYPE_PLAYER,            /* itype */
@@ -1071,7 +1095,7 @@ PlayerctlPlayer *playerctl_player_new_for_source(const gchar *player_name,
 }
 
 /**
- * playerctl_player_new_for_name:
+ * playerctl_player_new_from_name:
  * @player_name: The name type to use to find the player
  *
  * Allocates a new #PlayerctlPlayer and tries to connect to the bus name
@@ -1080,7 +1104,7 @@ PlayerctlPlayer *playerctl_player_new_for_source(const gchar *player_name,
  * Returns:(transfer full): A new #PlayerctlPlayer connected to an instance of
  * the player or NULL if an error occurred
  */
-PlayerctlPlayer *playerctl_player_new_for_name(PlayerctlPlayerName *player_name, GError **err) {
+PlayerctlPlayer *playerctl_player_new_from_name(PlayerctlPlayerName *player_name, GError **err) {
     GError *tmp_error = NULL;
     PlayerctlPlayer *player;
 
@@ -1101,8 +1125,11 @@ PlayerctlPlayer *playerctl_player_new_for_name(PlayerctlPlayerName *player_name,
  * @self: a #PlayerctlPlayer
  * @event: the event to subscribe to
  * @callback: the callback to run on the event
+ * @err (allow-none): the location of a #GError or %NULL
  *
  * A convenience function for bindings to subscribe to an event with a callback
+ *
+ * Deprecated: 2.0.0
  */
 void playerctl_player_on(PlayerctlPlayer *self, const gchar *event,
                                      GClosure *callback, GError **err) {
@@ -1520,6 +1547,14 @@ void playerctl_player_set_position(PlayerctlPlayer *self, gint64 position,
     }
 }
 
+/**
+ * playerctl_player_set_loop_status:
+ * @self: a #PlayerctlPlayer
+ * @status: the requested #PlayerctlLoopStatus to set the player to
+ * @err: (allow-none): the location of a #GError or %NULL
+ *
+ * Set the loop status of the player. Can be set to either None, Track, or Playlist.
+ */
 void playerctl_player_set_loop_status(PlayerctlPlayer *self,
                                       PlayerctlLoopStatus status,
                                       GError **err) {
@@ -1538,6 +1573,14 @@ void playerctl_player_set_loop_status(PlayerctlPlayer *self,
     org_mpris_media_player2_player_set_loop_status(self->priv->proxy, status_str);
 }
 
+/**
+ * playerctl_player_set_shuffle:
+ * @self: a #PlayerctlPlayer
+ * @shuffle: whether to enable shuffle
+ * @err (allow-none): the location of a #GError or %NULL
+ *
+ * Request to set the shuffle state of the player, either on or off.
+ */
 void playerctl_player_set_shuffle(PlayerctlPlayer *self,
                                   gboolean shuffle,
                                   GError **err) {

playerctl/playerctl-player.h

@@ -30,7 +30,7 @@
 
 /**
  * SECTION: playerctl-player
- * @short_description: A class to control an MPRIS player
+ * @short_description: A class to control a media player.
  */
 #define PLAYERCTL_TYPE_PLAYER (playerctl_player_get_type())
 #define PLAYERCTL_PLAYER(obj) \
@@ -71,8 +71,8 @@ PlayerctlPlayer *playerctl_player_new_for_source(const gchar *player_name,
                                                  PlayerctlSource source,
                                                  GError **err);
 
-PlayerctlPlayer *playerctl_player_new_for_name(PlayerctlPlayerName *player_name,
-                                               GError **err);
+PlayerctlPlayer *playerctl_player_new_from_name(PlayerctlPlayerName *player_name,
+                                                GError **err);
 
 /**
  * PlayerctlPlaybackStatus: