summaryrefslogtreecommitdiffstats
path: root/m_property.h
diff options
context:
space:
mode:
authoralbeu <albeu@b3059339-0415-0410-9bf9-f77b7e298cf2>2006-04-24 19:20:04 +0000
committeralbeu <albeu@b3059339-0415-0410-9bf9-f77b7e298cf2>2006-04-24 19:20:04 +0000
commitf0f01dd903351cb8e32863341810fd534e0ea33d (patch)
treee4c757042a683538c35a58f4d526eab7abcfc5e2 /m_property.h
parent7bad22647204c442301139f726dd56575504d0ff (diff)
downloadmpv-f0f01dd903351cb8e32863341810fd534e0ea33d.tar.bz2
mpv-f0f01dd903351cb8e32863341810fd534e0ea33d.tar.xz
Doxygen attack!
git-svn-id: svn://svn.mplayerhq.hu/mplayer/trunk@18259 b3059339-0415-0410-9bf9-f77b7e298cf2
Diffstat (limited to 'm_property.h')
-rw-r--r--m_property.h148
1 files changed, 119 insertions, 29 deletions
diff --git a/m_property.h b/m_property.h
index 269ff1b58f..46eacbb46d 100644
--- a/m_property.h
+++ b/m_property.h
@@ -1,50 +1,136 @@
-// Get the current value
-#define M_PROPERTY_GET 0
-// Get a string representing the current value
-#define M_PROPERTY_PRINT 1
-// Set a new value
-#define M_PROPERTY_SET 2
-// Set a new value from a string
-#define M_PROPERTY_PARSE 3
-// Increment the property
-#define M_PROPERTY_STEP_UP 4
-// Decrement the property
-#define M_PROPERTY_STEP_DOWN 5
-
-// Return values for the control function
+/// \defgroup Properties
+///
+/// Properties provide an interface to query and set the state of various
+/// things in MPlayer. The API is based on the \ref Options API like the
+/// \ref Config, but instead of using variables, properties use an ioctl like
+/// function. The function is used to perform various actions like get and set
+/// (see \ref PropertyActions).
+///@{
+
+/// \file
+
+/// \defgroup PropertyActions Property actions
+/// \ingroup Properties
+///@{
+
+/// Get the current value.
+/** \param arg Pointer to a variable of the right type.
+ */
+#define M_PROPERTY_GET 0
+
+/// Get a string representing the current value.
+/** Set the variable to a newly allocated string or NULL.
+ * \param arg Pointer to a char* variable.
+ */
+#define M_PROPERTY_PRINT 1
+
+/// Set a new value.
+/** The variable is updated to the value actually set.
+ * \param arg Pointer to a variable of the right type.
+ */
+#define M_PROPERTY_SET 2
+
+/// Set a new value from a string.
+/** \param arg String containing the value.
+ */
+#define M_PROPERTY_PARSE 3
+
+/// Increment the current value.
+/** The sign of the argument is also taken into account if applicable.
+ * \param arg Pointer to a variable of the right type or NULL.
+ */
+#define M_PROPERTY_STEP_UP 4
+
+/// Decrement the current value.
+/** The sign of the argument is also taken into account if applicable.
+ * \param arg Pointer to a variable of the right type or NULL.
+ */
+#define M_PROPERTY_STEP_DOWN 5
+
+///@}
+
+/// \defgroup PropertyActionsReturn Property actions return code
+/// \ingroup Properties
+/// \brief Return values for the control function.
+///@{
+
+/// Returned on success.
#define M_PROPERTY_OK 1
+
+/// Returned on error.
#define M_PROPERTY_ERROR 0
-// Returned when the property can't be used, for ex something about
-// the subs while playing audio only
+
+/// \brief Returned when the property can't be used, for ex something about
+/// the subs while playing audio only
#define M_PROPERTY_UNAVAILABLE -1
-// Returned if the requested action is not implemented
+
+/// Returned if the requested action is not implemented.
#define M_PROPERTY_NOT_IMPLEMENTED -2
-// Returned when asking for a property that doesn't exist
+
+/// Returned when asking for a property that doesn't exist.
#define M_PROPERTY_UNKNOWN -3
-// Returned when the action can't be done (like setting the volume when edl mute)
+
+/// Returned when the action can't be done (like setting the volume when edl mute).
#define M_PROPERTY_DISABLED -4
+///@}
+
+/// \ingroup Properties
+/// \brief Property action callback.
typedef int(*m_property_ctrl_f)(m_option_t* prop,int action,void* arg);
+/// Do an action on a property.
+/** \param prop The property.
+ * \param action See \ref PropertyActions.
+ * \param arg Argument, usually a pointer to the data type used by the property.
+ * \return See \ref PropertyActionsReturn.
+ */
int m_property_do(m_option_t* prop, int action, void* arg);
+/// Print the current value of a property.
+/** \param prop The property.
+ * \return A newly allocated string with current value or NULL on error.
+ */
char* m_property_print(m_option_t* prop);
+/// Set a property.
+/** \param prop The property.
+ * \param txt The value to set.
+ * \return 1 on success, 0 on error.
+ */
int m_property_parse(m_option_t* prop, char* txt);
+/// Print a list of properties.
void m_properties_print_help_list(m_option_t* list);
+/// Expand a property string.
+/** This function allow to print strings containing property values.
+ * ${NAME} is expanded to the value of property NAME or an empty
+ * string in case of error. $(NAME:STR) expand STR only if the property
+ * NAME is available.
+ *
+ * \param prop_list An array of \ref m_option describing the available
+ * properties.
+ * \param str The string to expand.
+ * \return The newly allocated expanded string.
+ */
char* m_properties_expand_string(m_option_t* prop_list,char* str);
// Helpers to use MPlayer's properties
+/// Get an MPlayer property.
m_option_t* mp_property_find(char* name);
+/// Do an action with an MPlayer property.
int mp_property_do(char* name,int action, void* val);
-// Helpers for property implementations
+/// \defgroup PropertyImplHelper Property implementation helpers
+/// \ingroup Properties
+/// \brief Helper functions for common property types.
+///@{
+/// Clamp a value according to \ref m_option::min and \ref m_option::max.
#define M_PROPERTY_CLAMP(prop,val) do { \
if(((prop)->flags & M_OPT_MIN) && (val) < (prop)->min) \
(val) = (prop)->min; \
@@ -52,37 +138,41 @@ int mp_property_do(char* name,int action, void* val);
(val) = (prop)->max; \
} while(0)
-// Implement get
+/// Implement get.
int m_property_int_ro(m_option_t* prop,int action,
void* arg,int var);
-// Implement set, get and step up/down
+/// Implement set, get and step up/down.
int m_property_int_range(m_option_t* prop,int action,
void* arg,int* var);
-// Same but cycle
+/// Same as m_property_int_range but cycle.
int m_property_choice(m_option_t* prop,int action,
void* arg,int* var);
-// Switch betwen min and max
+/// Switch betwen min and max.
int m_property_flag(m_option_t* prop,int action,
void* arg,int* var);
-// Implement get, print
+/// Implement get, print.
int m_property_float_ro(m_option_t* prop,int action,
void* arg,float var);
-// Implement set, get and step up/down
+/// Implement set, get and step up/down
int m_property_float_range(m_option_t* prop,int action,
void* arg,float* var);
-// float with a print function which print the time in ms
+/// float with a print function which print the time in ms
int m_property_delay(m_option_t* prop,int action,
void* arg,float* var);
-// Implement get, print
+/// Implement get, print
int m_property_double_ro(m_option_t* prop,int action,
void* arg,double var);
-// get/print the string
+/// get/print the string
int m_property_string_ro(m_option_t* prop,int action,void* arg, char* str);
+
+///@}
+
+///@}