summaryrefslogtreecommitdiff
path: root/legacy/emotion/src/lib/Emotion.h
diff options
context:
space:
mode:
authorRafael Antognolli <antognolli@gmail.com>2011-06-30 18:31:39 +0000
committerRafael Antognolli <antognolli@gmail.com>2011-06-30 18:31:39 +0000
commitdd72eeea0e299f66d5a260185032233f181bce18 (patch)
tree73dfb3fed0f23c150d521244a75e44fce444799c /legacy/emotion/src/lib/Emotion.h
parent662dea3019b8efaf67d91f5731beb2a531d20e42 (diff)
emotion/doc - documented the initialization functions.
SVN revision: 60880
Diffstat (limited to '')
-rw-r--r--legacy/emotion/src/lib/Emotion.h152
1 files changed, 152 insertions, 0 deletions
diff --git a/legacy/emotion/src/lib/Emotion.h b/legacy/emotion/src/lib/Emotion.h
index f84153728f..b13b8ea21a 100644
--- a/legacy/emotion/src/lib/Emotion.h
+++ b/legacy/emotion/src/lib/Emotion.h
@@ -29,6 +29,12 @@
29# endif 29# endif
30#endif /* ! _WIN32 */ 30#endif /* ! _WIN32 */
31 31
32/**
33 * @file Emotion.h
34 * @brief The file that provides Emotion the API, with functions available for
35 * play, seek, change volume, etc.
36 */
37
32enum _Emotion_Module 38enum _Emotion_Module
33{ 39{
34 EMOTION_MODULE_XINE, 40 EMOTION_MODULE_XINE,
@@ -116,10 +122,152 @@ extern "C" {
116#endif 122#endif
117 123
118/* api calls available */ 124/* api calls available */
125
126/**
127 * @brief How to create, initialize, manipulate and connect to signals of an
128 * Emotion object.
129 * @defgroup Emotion_API API available for manipulating Emotion object.
130 *
131 * @{
132 *
133 * @li Add the description of modules here.
134 * @li Basic emotion example
135 * @li Signals available
136 */
137
138/**
139 * @defgroup Emotion_Init Creation and initialization functions
140 */
141
142/**
143 * @defgroup Emotion_Audio Audio control functions
144 */
145
146/**
147 * @defgroup Emotion_Video Video control functions
148 */
149
150/**
151 * @brief Add an emotion object to the canvas.
152 *
153 * @param evas The canvas where the object will be added to.
154 * @return The emotion object just created.
155 *
156 * This function creates an emotion object and adds it to the specified @p evas.
157 * The returned object can be manipulated as any other Evas object, using the
158 * default object manipulation functions - evas_object_*.
159 *
160 * After creating the object with this function, it's still necessary to
161 * initialize it with emotion_object_init(), and if an audio file is going to be
162 * played with this object instead of a video, use
163 * emotion_object_video_mute_set().
164 *
165 * The next step is to open the desired file with emotion_object_file_set(), and
166 * start playing it with emotion_object_play_set().
167 *
168 * @see emotion_object_init()
169 * @see emotion_object_video_mute_set()
170 * @see emotion_object_file_set()
171 * @see emotion_object_play_set()
172 *
173 * @ingroup Emotion_Init
174 */
119EAPI Evas_Object *emotion_object_add (Evas *evas); 175EAPI Evas_Object *emotion_object_add (Evas *evas);
176
177/**
178 * @brief Set the specified option for the current module.
179 *
180 * @param obj The emotion object which the option is being set to.
181 * @param opt The option that is being set. Currently supported optiosn: "video"
182 * and "audio".
183 * @param val The value of the option. Currently only supports "off" (?!?!?!)
184 *
185 * This function allows one to mute the video or audio of the emotion object.
186 *
187 * @note Please don't use this function, consider using
188 * emotion_object_audio_mute_set() and emotion_object_video_mute_set() instead.
189 *
190 * @see emotion_object_audio_mute_set()
191 * @see emotion_object_video_mute_set()
192 *
193 * @ingroup Emotion_Audio
194 * @ingroup Emotion_Video
195 */
120EAPI void emotion_object_module_option_set (Evas_Object *obj, const char *opt, const char *val); 196EAPI void emotion_object_module_option_set (Evas_Object *obj, const char *opt, const char *val);
197
198/**
199 * @brief Initializes an emotion object with the specified module.
200 *
201 * @param obj The emotion object to be initialized.
202 * @param module_filename The name of the module to be used (gstreamer or xine).
203 * @return @c EINA_TRUE if the specified module was successfully initialized for
204 * this object, @c EINA_FALSE otherwise.
205 *
206 * This function is required after creating the emotion object, in order to
207 * specify which module will be used with this object. Different objects can
208 * use different modules to play a media file. The current supported modules are
209 * @b gstreamer and @b xine.
210 *
211 * To use any of them, you need to make sure that support for them was compiled
212 * correctly.
213 *
214 * @note It's possible to disable the build of a module with
215 * --disable-module_name.
216 *
217 * @see emotion_object_add()
218 * @see emotion_object_file_set()
219 *
220 * @ingroup Emotion_Init
221 */
121EAPI Eina_Bool emotion_object_init (Evas_Object *obj, const char *module_filename); 222EAPI Eina_Bool emotion_object_init (Evas_Object *obj, const char *module_filename);
223
224/**
225 * @brief Set the file to be played in the Emotion object.
226 *
227 * @param obj The emotion object where the file is being loaded.
228 * @param filename Path to the file to be loaded. It can be absolute or relative
229 * path.
230 * @return EINA_TRUE if the new file could be loaded successfully, and
231 * EINA_FALSE if the file could not be loaded. This happens when the filename is
232 * could not be found, when the module couldn't open the file, when no module is
233 * initialized in this object, or when the @p filename is the same as the
234 * one previously set.
235 *
236 * This function sets the file to be used with this emotion object. If the
237 * object already has another file set, this file will be unset and unloaded,
238 * and the new file will be loaded to this emotion object. The seek position
239 * will be set to 0, and the emotion object will be paused, instead of playing.
240 *
241 * If there was already a filename set, and it's the same as the one being set
242 * now, this function does nothing and returns EINA_FALSE.
243 *
244 * Use @c NULL as argument to @p filename if you want to unload the current file
245 * but don't want to load anything else.
246 *
247 * @see emotion_object_init()
248 * @see emotion_object_play_set()
249 * @see emotion_object_file_get()
250 *
251 * @ingroup Emotion_Init
252 */
122EAPI Eina_Bool emotion_object_file_set (Evas_Object *obj, const char *filename); 253EAPI Eina_Bool emotion_object_file_set (Evas_Object *obj, const char *filename);
254
255/**
256 * @brief Get the filename of the file associated with the emotion object.
257 *
258 * @param obj The emotion object from which the filename will be retrieved.
259 * @return The path to the file loaded into this emotion object.
260 *
261 * This function returns the path of the file loaded in this emotion object. If
262 * no object is loaded, it will return @c NULL.
263 *
264 * @note Don't free or change the string returned by this function in any way.
265 * If you want to unset it, use @c emotion_object_file_set(obj, NULL).
266 *
267 * @see emotion_object_file_set()
268 *
269 * @ingroup Emotion_Init
270 */
123EAPI const char *emotion_object_file_get (const Evas_Object *obj); 271EAPI const char *emotion_object_file_get (const Evas_Object *obj);
124EAPI void emotion_object_play_set (Evas_Object *obj, Eina_Bool play); 272EAPI void emotion_object_play_set (Evas_Object *obj, Eina_Bool play);
125EAPI Eina_Bool emotion_object_play_get (const Evas_Object *obj); 273EAPI Eina_Bool emotion_object_play_get (const Evas_Object *obj);
@@ -183,6 +331,10 @@ EAPI Eina_Bool emotion_object_extension_can_play_fast_get(const Evas_Object *
183EAPI Eina_Bool emotion_object_extension_may_play_fast_get(const char *file); 331EAPI Eina_Bool emotion_object_extension_may_play_fast_get(const char *file);
184EAPI Eina_Bool emotion_object_extension_may_play_get(const char *file); 332EAPI Eina_Bool emotion_object_extension_may_play_get(const char *file);
185 333
334/**
335 * @}
336 */
337
186#ifdef __cplusplus 338#ifdef __cplusplus
187} 339}
188#endif 340#endif