From f5c2e3d6e2372546c46dd32ceab1a5c41e19465b Mon Sep 17 00:00:00 2001 From: wm4 Date: Sat, 8 Nov 2014 09:59:38 +0100 Subject: [PATCH] client API: deprecate some events Following the discussion in #1253. The events won't be removed for a while, though. (Or maybe never, unless we run out of bits for the uint64_t event mask.) This is not a real change (the events still work, and the alternative mechanisms were established a few API revisions earlier), but for the sake of notifying API users, update DOCS/client-api-changes.rst. --- DOCS/client-api-changes.rst | 9 +++++++++ DOCS/man/lua.rst | 25 +++---------------------- libmpv/client.h | 23 +++++++++++++++++++++++ 3 files changed, 35 insertions(+), 22 deletions(-) diff --git a/DOCS/client-api-changes.rst b/DOCS/client-api-changes.rst index eee27c6a3f..9490fa4b7a 100644 --- a/DOCS/client-api-changes.rst +++ b/DOCS/client-api-changes.rst @@ -31,6 +31,15 @@ API changes - add --stop-playback-on-init-failure option, and make it the default behavior for libmpv only - add qthelper.hpp set_option_variant() + - mark the following events as deprecated: + MPV_EVENT_TRACKS_CHANGED + MPV_EVENT_TRACK_SWITCHED + MPV_EVENT_PAUSE + MPV_EVENT_UNPAUSE + MPV_EVENT_METADATA_UPDATE + MPV_EVENT_CHAPTER_CHANGE + They are handled better with mpv_observe_property() as mentioned in + the documentation comments. They are not removed and still work. 1.8 - add qthelper.hpp 1.7 - add mpv_command_node(), mpv_command_node_async() 1.6 - modify "core-idle" property behavior diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst index f35af85079..fbba495a4f 100644 --- a/DOCS/man/lua.rst +++ b/DOCS/man/lua.rst @@ -648,28 +648,11 @@ List of events ``playback-restart`` Start of playback after seek or after file was loaded. -``tracks-changed`` - The list of video/audio/sub tracks was updated. (This happens on playback - start, and very rarely during playback.) - -``track-switched`` - A video/audio/subtitle track was switched on or off. This usually happens - when the user (or a script) changes the subtitle track and so on. - ``idle`` Idle mode is entered. This happens when playback ended, and the player was started with ``--idle`` or ``--force-window``. This mode is implicitly ended when the ``start-file`` or ``shutdown`` events happen. -``pause`` - Playback was paused. This also happens when for example the player is - paused on low network cache. Then the event type indicates the pause state - (like the property "pause" as opposed to the "core-idle" property), and you - might receive multiple ``pause`` events in a row. - -``unpause`` - Playback was unpaused. See above for details. - ``tick`` Called after a video frame was displayed. This is a hack, and you should avoid using it. Use timers instead and maybe watch pausing/unpausing events @@ -729,11 +712,9 @@ List of events ``audio-reconfig`` Happens on audio output or filter reconfig. -``metadata-update`` - Metadata (like file tags) was updated. - -``chapter-change`` - The current chapter possibly changed. +The following events also happen, but are deprecated: ``tracks-changed``, +``track-switched``, ``pause``, ``unpause``, ``metadata-update``, +``chapter-change``. Use ``mp.observe_property()`` instead. Extras ------ diff --git a/libmpv/client.h b/libmpv/client.h index cf8b99a986..4ad0a5e65a 100644 --- a/libmpv/client.h +++ b/libmpv/client.h @@ -952,10 +952,18 @@ typedef enum mpv_event_id { * The list of video/audio/subtitle tracks was changed. (E.g. a new track * was found. This doesn't necessarily indicate a track switch; for this, * MPV_EVENT_TRACK_SWITCHED is used.) + * + * @deprecated This is equivalent to using mpv_observe_property() on the + * "track-list" property. The event is redundant, and might + * be removed in the far future. */ MPV_EVENT_TRACKS_CHANGED = 9, /** * A video/audio/subtitle track was switched on or off. + * + * @deprecated This is equivalent to using mpv_observe_property() on the + * "vid", "aid", and "sid" properties. The event is redundant, + * and might be removed in the far future. */ MPV_EVENT_TRACK_SWITCHED = 10, /** @@ -981,10 +989,17 @@ typedef enum mpv_event_id { * If you don't want to deal with this, use mpv_observe_property() on the * "pause" property and ignore MPV_EVENT_PAUSE/UNPAUSE. Likewise, the * "core-idle" property tells you whether video is actually playing or not. + * + * @deprecated The event is redundant with mpv_observe_property() as + * mentioned above, and might be removed in the far future. */ MPV_EVENT_PAUSE = 12, /** * Playback was unpaused. See MPV_EVENT_PAUSE for not so obvious details. + * + * @deprecated The event is redundant with mpv_observe_property() as + * explained in the MPV_EVENT_PAUSE comments, and might be + * removed in the far future. */ MPV_EVENT_UNPAUSE = 13, /** @@ -1031,6 +1046,10 @@ typedef enum mpv_event_id { * Happens when metadata (like file tags) is possibly updated. (It's left * unspecified whether this happens on file start or only when it changes * within a file.) + * + * @deprecated This is equivalent to using mpv_observe_property() on the + * "metadata" property. The event is redundant, and might + * be removed in the far future. */ MPV_EVENT_METADATA_UPDATE = 19, /** @@ -1052,6 +1071,10 @@ typedef enum mpv_event_id { MPV_EVENT_PROPERTY_CHANGE = 22, /** * Happens when the current chapter changes. + * + * @deprecated This is equivalent to using mpv_observe_property() on the + * "chapter" property. The event is redundant, and might + * be removed in the far future. */ MPV_EVENT_CHAPTER_CHANGE = 23 // Internal note: adjust INTERNAL_EVENT_BASE when adding new events.