4 /// \defgroup Properties
6 /// Properties provide an interface to query and set the state of various
7 /// things in MPlayer. The API is based on the \ref Options API like the
8 /// \ref Config, but instead of using variables, properties use an ioctl like
9 /// function. The function is used to perform various actions like get and set
10 /// (see \ref PropertyActions).
15 /// \defgroup PropertyActions Property actions
16 /// \ingroup Properties
19 /// Get the current value.
20 /** \param arg Pointer to a variable of the right type.
22 #define M_PROPERTY_GET 0
24 /// Get a string representing the current value.
25 /** Set the variable to a newly allocated string or NULL.
26 * \param arg Pointer to a char* variable.
28 #define M_PROPERTY_PRINT 1
31 /** The variable is updated to the value actually set.
32 * \param arg Pointer to a variable of the right type.
34 #define M_PROPERTY_SET 2
36 /// Set a new value from a string.
37 /** \param arg String containing the value.
39 #define M_PROPERTY_PARSE 3
41 /// Increment the current value.
42 /** The sign of the argument is also taken into account if applicable.
43 * \param arg Pointer to a variable of the right type or NULL.
45 #define M_PROPERTY_STEP_UP 4
47 /// Decrement the current value.
48 /** The sign of the argument is also taken into account if applicable.
49 * \param arg Pointer to a variable of the right type or NULL.
51 #define M_PROPERTY_STEP_DOWN 5
53 /// Get a string containg a parsable representation.
54 /** Set the variable to a newly allocated string or NULL.
55 * \param arg Pointer to a char* variable.
57 #define M_PROPERTY_TO_STRING 6
59 /// Pass down an action to a sub-property.
60 #define M_PROPERTY_KEY_ACTION 7
62 /// Get a m_option describing the property.
63 #define M_PROPERTY_GET_TYPE 8
67 /// \defgroup PropertyActionsArg Property actions argument type
68 /// \ingroup Properties
69 /// \brief Types used as action argument.
72 /// Argument for \ref M_PROPERTY_KEY_ACTION
77 } m_property_action_t
;
81 /// \defgroup PropertyActionsReturn Property actions return code
82 /// \ingroup Properties
83 /// \brief Return values for the control function.
86 /// Returned on success.
87 #define M_PROPERTY_OK 1
89 /// Returned on error.
90 #define M_PROPERTY_ERROR 0
92 /// \brief Returned when the property can't be used, for example something about
93 /// the subs while playing audio only
94 #define M_PROPERTY_UNAVAILABLE -1
96 /// Returned if the requested action is not implemented.
97 #define M_PROPERTY_NOT_IMPLEMENTED -2
99 /// Returned when asking for a property that doesn't exist.
100 #define M_PROPERTY_UNKNOWN -3
102 /// Returned when the action can't be done (like setting the volume when edl mute).
103 #define M_PROPERTY_DISABLED -4
107 /// \ingroup Properties
108 /// \brief Property action callback.
109 typedef int(*m_property_ctrl_f
)(m_option_t
* prop
,int action
,void* arg
,void *ctx
);
111 /// Do an action on a property.
112 /** \param prop_list The list of properties.
113 * \param prop The path of the property.
114 * \param action See \ref PropertyActions.
115 * \param arg Argument, usually a pointer to the data type used by the property.
116 * \return See \ref PropertyActionsReturn.
118 int m_property_do(m_option_t
* prop_list
, const char* prop
,
119 int action
, void* arg
, void *ctx
);
121 /// Print a list of properties.
122 void m_properties_print_help_list(m_option_t
* list
);
124 /// Expand a property string.
125 /** This function allows to print strings containing property values.
126 * ${NAME} is expanded to the value of property NAME or an empty
127 * string in case of error. $(NAME:STR) expand STR only if the property
130 * \param prop_list An array of \ref m_option describing the available
132 * \param str The string to expand.
133 * \return The newly allocated expanded string.
135 char* m_properties_expand_string(m_option_t
* prop_list
,char* str
, void *ctx
);
137 // Helpers to use MPlayer's properties
139 /// Do an action with an MPlayer property.
140 int mp_property_do(const char* name
,int action
, void* val
, void *ctx
);
142 /// Get the value of a property as a string suitable for display in an UI.
143 char* mp_property_print(const char *name
, void* ctx
);
145 /// \defgroup PropertyImplHelper Property implementation helpers
146 /// \ingroup Properties
147 /// \brief Helper functions for common property types.
150 /// Clamp a value according to \ref m_option::min and \ref m_option::max.
151 #define M_PROPERTY_CLAMP(prop,val) do { \
152 if(((prop)->flags & M_OPT_MIN) && (val) < (prop)->min) \
153 (val) = (prop)->min; \
154 else if(((prop)->flags & M_OPT_MAX) && (val) > (prop)->max) \
155 (val) = (prop)->max; \
159 int m_property_int_ro(m_option_t
* prop
,int action
,
162 /// Implement set, get and step up/down.
163 int m_property_int_range(m_option_t
* prop
,int action
,
166 /// Same as m_property_int_range but cycle.
167 int m_property_choice(m_option_t
* prop
,int action
,
170 /// Switch betwen min and max.
171 int m_property_flag(m_option_t
* prop
,int action
,
174 /// Implement get, print.
175 int m_property_float_ro(m_option_t
* prop
,int action
,
176 void* arg
,float var
);
178 /// Implement set, get and step up/down
179 int m_property_float_range(m_option_t
* prop
,int action
,
180 void* arg
,float* var
);
182 /// float with a print function which print the time in ms
183 int m_property_delay(m_option_t
* prop
,int action
,
184 void* arg
,float* var
);
186 /// Implement get, print
187 int m_property_double_ro(m_option_t
* prop
,int action
,
188 void* arg
,double var
);
191 int m_property_time_ro(m_option_t
* prop
,int action
,
192 void* arg
,double var
);
194 /// get/print the string
195 int m_property_string_ro(m_option_t
* prop
,int action
,void* arg
, char* str
);
197 /// get/print a bitrate
198 int m_property_bitrate(m_option_t
* prop
,int action
,void* arg
,int rate
);
204 #endif /* M_PROPERTY_H */