Ignore svn changes up to r30324
[mplayer/glamo.git] / m_property.h
blob1bab02d6f1c130af5cdc6cbc06194977aac9ef03
1 #ifndef MPLAYER_M_PROPERTY_H
2 #define MPLAYER_M_PROPERTY_H
4 #include "m_option.h"
6 /// \defgroup Properties
7 ///
8 /// Properties provide an interface to query and set the state of various
9 /// things in MPlayer. The API is based on the \ref Options API like the
10 /// \ref Config, but instead of using variables, properties use an ioctl like
11 /// function. The function is used to perform various actions like get and set
12 /// (see \ref PropertyActions).
13 ///@{
15 /// \file
17 /// \defgroup PropertyActions Property actions
18 /// \ingroup Properties
19 ///@{
21 /// Get the current value.
22 /** \param arg Pointer to a variable of the right type.
24 #define M_PROPERTY_GET 0
26 /// Get a string representing the current value.
27 /** Set the variable to a newly allocated string or NULL.
28 * \param arg Pointer to a char* variable.
30 #define M_PROPERTY_PRINT 1
32 /// Set a new value.
33 /** The variable is updated to the value actually set.
34 * \param arg Pointer to a variable of the right type.
36 #define M_PROPERTY_SET 2
38 /// Set a new value from a string.
39 /** \param arg String containing the value.
41 #define M_PROPERTY_PARSE 3
43 /// Increment the current value.
44 /** The sign of the argument is also taken into account if applicable.
45 * \param arg Pointer to a variable of the right type or NULL.
47 #define M_PROPERTY_STEP_UP 4
49 /// Decrement the current value.
50 /** The sign of the argument is also taken into account if applicable.
51 * \param arg Pointer to a variable of the right type or NULL.
53 #define M_PROPERTY_STEP_DOWN 5
55 /// Get a string containg a parsable representation.
56 /** Set the variable to a newly allocated string or NULL.
57 * \param arg Pointer to a char* variable.
59 #define M_PROPERTY_TO_STRING 6
61 /// Pass down an action to a sub-property.
62 #define M_PROPERTY_KEY_ACTION 7
64 /// Get a m_option describing the property.
65 #define M_PROPERTY_GET_TYPE 8
67 ///@}
69 /// \defgroup PropertyActionsArg Property actions argument type
70 /// \ingroup Properties
71 /// \brief Types used as action argument.
72 ///@{
74 /// Argument for \ref M_PROPERTY_KEY_ACTION
75 typedef struct {
76 const char* key;
77 int action;
78 void* arg;
79 } m_property_action_t;
81 ///@}
83 /// \defgroup PropertyActionsReturn Property actions return code
84 /// \ingroup Properties
85 /// \brief Return values for the control function.
86 ///@{
88 /// Returned on success.
89 #define M_PROPERTY_OK 1
91 /// Returned on error.
92 #define M_PROPERTY_ERROR 0
94 /// \brief Returned when the property can't be used, for example something about
95 /// the subs while playing audio only
96 #define M_PROPERTY_UNAVAILABLE -1
98 /// Returned if the requested action is not implemented.
99 #define M_PROPERTY_NOT_IMPLEMENTED -2
101 /// Returned when asking for a property that doesn't exist.
102 #define M_PROPERTY_UNKNOWN -3
104 /// Returned when the action can't be done (like setting the volume when edl mute).
105 #define M_PROPERTY_DISABLED -4
107 ///@}
109 /// \ingroup Properties
110 /// \brief Property action callback.
111 typedef int(*m_property_ctrl_f)(const m_option_t* prop,int action,void* arg,void *ctx);
113 /// Do an action on a property.
114 /** \param prop_list The list of properties.
115 * \param prop The path of the property.
116 * \param action See \ref PropertyActions.
117 * \param arg Argument, usually a pointer to the data type used by the property.
118 * \return See \ref PropertyActionsReturn.
120 int m_property_do(const m_option_t* prop_list, const char* prop,
121 int action, void* arg, void *ctx);
123 /// Print a list of properties.
124 void m_properties_print_help_list(const m_option_t* list);
126 /// Expand a property string.
127 /** This function allows to print strings containing property values.
128 * ${NAME} is expanded to the value of property NAME or an empty
129 * string in case of error. $(NAME:STR) expand STR only if the property
130 * NAME is available.
132 * \param prop_list An array of \ref m_option describing the available
133 * properties.
134 * \param str The string to expand.
135 * \return The newly allocated expanded string.
137 char* m_properties_expand_string(const m_option_t* prop_list,char* str, void *ctx);
139 // Helpers to use MPlayer's properties
141 /// Do an action with an MPlayer property.
142 int mp_property_do(const char* name,int action, void* val, void *ctx);
144 /// Get the value of a property as a string suitable for display in an UI.
145 char* mp_property_print(const char *name, void* ctx);
147 /// \defgroup PropertyImplHelper Property implementation helpers
148 /// \ingroup Properties
149 /// \brief Helper functions for common property types.
150 ///@{
152 /// Clamp a value according to \ref m_option::min and \ref m_option::max.
153 #define M_PROPERTY_CLAMP(prop,val) do { \
154 if(((prop)->flags & M_OPT_MIN) && (val) < (prop)->min) \
155 (val) = (prop)->min; \
156 else if(((prop)->flags & M_OPT_MAX) && (val) > (prop)->max) \
157 (val) = (prop)->max; \
158 } while(0)
160 /// Implement get.
161 int m_property_int_ro(const m_option_t* prop,int action,
162 void* arg,int var);
164 /// Implement set, get and step up/down.
165 int m_property_int_range(const m_option_t* prop,int action,
166 void* arg,int* var);
168 /// Same as m_property_int_range but cycle.
169 int m_property_choice(const m_option_t* prop,int action,
170 void* arg,int* var);
172 int m_property_flag_ro(const m_option_t* prop,int action,
173 void* arg,int var);
175 /// Switch betwen min and max.
176 int m_property_flag(const m_option_t* prop,int action,
177 void* arg,int* var);
179 /// Implement get, print.
180 int m_property_float_ro(const m_option_t* prop,int action,
181 void* arg,float var);
183 /// Implement set, get and step up/down
184 int m_property_float_range(const m_option_t* prop,int action,
185 void* arg,float* var);
187 /// float with a print function which print the time in ms
188 int m_property_delay(const m_option_t* prop,int action,
189 void* arg,float* var);
191 /// Implement get, print
192 int m_property_double_ro(const m_option_t* prop,int action,
193 void* arg,double var);
195 /// Implement print
196 int m_property_time_ro(const m_option_t* prop,int action,
197 void* arg,double var);
199 /// get/print the string
200 int m_property_string_ro(const m_option_t* prop,int action,void* arg, char* str);
202 /// get/print a bitrate
203 int m_property_bitrate(const m_option_t* prop,int action,void* arg,int rate);
205 ///@}
207 ///@}
209 #endif /* MPLAYER_M_PROPERTY_H */