libobs: Deprecate v1 of obs_properties_add_button

With v1 of this function, it's unclear where exactly the data pointer
comes from or what it is. In fact, this is not determined by libobs, but
the consumer. libobs assumes that the caller of
obs_property_button_clicked passes an obs_context_data pointer, and then
passes the data pointer of that obs_context_data as the data pointer to
the callback.
In OBS Studio, this is always the private data of the associated object.
However, this assumes that there even is such an object (source/encoder/
etc), even though properties are meant to be free-standing. This is not
just philosophical, because with obs_get_source_properties you can
actually get an obs_properties_t that isn't associated with any specific
source, at which point you have no idea what the data pointer will be.

For this reason, obs_properties_add_button v1 needs to go.
obs_properties_add_button2 can be used as a drop-in replacement.
With v2, it's well-defined that the pointer you're passing as priv is
the pointer you get back in the callback as data. If you don't care
about it, simply pass NULL/nullptr.

Once v1 is removed in the future, obs_property_button_clicked should be
replaced with a variant that doesn't take a second argument, as that
argument will no longer be used anywhere.

docs/sphinx/reference-properties.rst

@@ -259,7 +259,14 @@ Property Object Functions
 ---------------------
 
 .. function:: obs_property_t *obs_properties_add_button(obs_properties_t *props, const char *name, const char *text, obs_property_clicked_t callback)
-              obs_property_t *obs_properties_add_button2(obs_properties_t *props, const char *name, const char *text, obs_property_clicked_t callback, void *priv)
+
+   Like :c:func:`obs_properties_add_button2`, except the value of the ``data`` argument in the callback is
+   determined by the caller of :c:func:`obs_property_button_clicked`, and as such unspecified by libobs.
+
+   .. deprecated:: 32.1
+   Use :c:func:`obs_properties_add_button2` instead.
+
+.. function:: obs_property_t *obs_properties_add_button2(obs_properties_t *props, const char *name, const char *text, obs_property_clicked_t callback, void *priv)
 
    Adds a button property.  This property does not actually store any
    settings; it's used to implement a button in user interface if the
@@ -270,11 +277,7 @@ Property Object Functions
 
    :param    name:        Setting identifier string
    :param    text:        Localized name shown to user
-   :param    callback:    Callback to be executed when the button is pressed. Note that if the property
-                          is created with :c:func:`obs_properties_add_button` instead of
-                          :c:func:`obs_properties_add_button2`, the value of ``data`` is determined by
-                          the caller of :c:func:`obs_property_button_clicked`, and as such unspecified
-                          by libobs.
+   :param    callback:    Callback to be executed when the button is pressed
    :param    priv:        Pointer passed back as the `data` argument of the callback
    :return:               The property
 

libobs/obs-properties.h

@@ -214,8 +214,8 @@ EXPORT obs_property_t *obs_properties_add_color(obs_properties_t *props, const c
 EXPORT obs_property_t *obs_properties_add_color_alpha(obs_properties_t *props, const char *name,
 						      const char *description);
 
-EXPORT obs_property_t *obs_properties_add_button(obs_properties_t *props, const char *name, const char *text,
-						 obs_property_clicked_t callback);
+OBS_DEPRECATED EXPORT obs_property_t *obs_properties_add_button(obs_properties_t *props, const char *name,
+								const char *text, obs_property_clicked_t callback);
 
 EXPORT obs_property_t *obs_properties_add_button2(obs_properties_t *props, const char *name, const char *text,
 						  obs_property_clicked_t callback, void *priv);