From ed8e738e0f7da90597732965fe4e8cd1feb9099a Mon Sep 17 00:00:00 2001 From: wm4 Date: Fri, 21 Sep 2012 12:19:59 +0200 Subject: commands: cosmetic changes mostly to m_property.h The Doxygen-style documentation comments were nothing but bloat. Also move mp_property_do() and mp_property_print() to command.h, where they should belong, and fix their argument types. m_property.c/h is supposed to be generic, while command.h provides declarations specific to the mplayer core. --- m_property.h | 196 +++++++++++++++++++++++------------------------------------ 1 file changed, 76 insertions(+), 120 deletions(-) (limited to 'm_property.h') diff --git a/m_property.h b/m_property.h index cca624b6db..99ab05ad62 100644 --- a/m_property.h +++ b/m_property.h @@ -21,145 +21,101 @@ #include "m_option.h" -/// \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 - -/// Get a string containg a parsable representation. -/** Set the variable to a newly allocated string or NULL. - * \param arg Pointer to a char* variable. - */ -#define M_PROPERTY_TO_STRING 6 - -/// Pass down an action to a sub-property. -#define M_PROPERTY_KEY_ACTION 7 - -/// Get a m_option describing the property. -#define M_PROPERTY_GET_TYPE 8 - -// Switch the property up/down by a given value. -// arg: (double) value to add to the property -#define M_PROPERTY_SWITCH 9 - -///@} - -/// \defgroup PropertyActionsArg Property actions argument type -/// \ingroup Properties -/// \brief Types used as action argument. -///@{ - -/// Argument for \ref M_PROPERTY_KEY_ACTION -typedef struct { +enum mp_property_action { + // Get the property type. This defines the fundamental data type read from + // or written to the property. + // If unimplemented, the m_option entry that defines the property is used. + // arg: const m_option** + M_PROPERTY_GET_TYPE, + + // Get the current value. + // arg: pointer to a variable of the type according to the property type + M_PROPERTY_GET, + + // Set a new value. The property wrapper will make sure that only valid + // values are set (e.g. according to the property type's min/max range). + // If unimplemented, the property is read-only. + // arg: pointer to a variable of the type according to the property type + M_PROPERTY_SET, + + // Get human readable string representing the current value. + // If unimplemented, the property wrapper uses the property type as + // fallback. + // arg: char** + M_PROPERTY_PRINT, + + // Switch the property up/down by a given value. + // If unimplemented, the property wrapper uses the property type as + // fallback. + // arg: double* (value to add to the property) + M_PROPERTY_SWITCH, + + // Set a new value from a string. The property wrapper parses this using the + // parse function provided by the property type. + // Can't be overridden by property implementations. + // arg: char* + M_PROPERTY_PARSE, + + // Get a string containing a parsable representation. + // Can't be overridden by property implementations. + // arg: char** + M_PROPERTY_TO_STRING, + + // Pass down an action to a sub-property. + // arg: struct m_property_action* + M_PROPERTY_KEY_ACTION, +}; + +// Argument for M_PROPERTY_KEY_ACTION +struct m_property_action { const char* key; int action; void* arg; -} m_property_action_t; - -///@} - -/// \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 - -/// \brief Returned when the property can't be used, for example something about -/// the subs while playing audio only -#define M_PROPERTY_UNAVAILABLE -1 +}; -/// Returned if the requested action is not implemented. -#define M_PROPERTY_NOT_IMPLEMENTED -2 +enum mp_property_return { + // Returned on success. + M_PROPERTY_OK = 1, -/// Returned when asking for a property that doesn't exist. -#define M_PROPERTY_UNKNOWN -3 + // Returned on error. + M_PROPERTY_ERROR = 0, -/// Returned when the action can't be done (like setting the volume when edl mute). -#define M_PROPERTY_DISABLED -4 + // Returned when the property can't be used, for example video related + // properties while playing audio only. + M_PROPERTY_UNAVAILABLE = -1, -///@} + // Returned if the requested action is not implemented. + M_PROPERTY_NOT_IMPLEMENTED = -2, -/// \ingroup Properties -/// \brief Property action callback. -typedef int(*m_property_ctrl_f)(const m_option_t* prop,int action,void* arg,void *ctx); + // Returned when asking for a property that doesn't exist. + M_PROPERTY_UNKNOWN = -3, +}; -/// Do an action on a property. -/** \param prop_list The list of properties. - * \param prop The path of 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(const m_option_t* prop_list, const char* prop, +// Access a property. +// action: one of m_property_action +// ctx: opaque value passed through to property implementation +// returns: one of mp_property_return +int m_property_do(const struct m_option* prop_list, const char* property_name, int action, void* arg, void *ctx); -/// Print a list of properties. +// Print a list of properties. void m_properties_print_help_list(const m_option_t* list); -/// Expand a property string. -/** This function allows to print strings containing property values. +// Expand a property string. +/* This function allows 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(const m_option_t* prop_list,char* str, void *ctx); - -// Helpers to use MPlayer's properties +char* m_properties_expand_string(const struct m_option* prop_list, char* str, + void *ctx); -/// Do an action with an MPlayer property. -int mp_property_do(const char* name,int action, void* val, void *ctx); - -/// Get the value of a property as a string suitable for display in an UI. -char* mp_property_print(const char *name, void* ctx); - -int m_property_int_ro(const m_option_t* prop, int action, void* arg, int var); -int m_property_float_ro(const m_option_t* prop, int action, void* arg, +// Trivial helpers for implementing properties. +int m_property_int_ro(const struct m_option* prop, int action, void* arg, + int var); +int m_property_float_ro(const struct m_option* prop, int action, void* arg, float var); -int m_property_double_ro(const m_option_t* prop, int action, void* arg, +int m_property_double_ro(const struct m_option* prop, int action, void* arg, double var); -///@} - #endif /* MPLAYER_M_PROPERTY_H */ -- cgit v1.2.3