src/lib/elm_video.h

   1 /**
   2  * @defgroup Video Video
   3  * @ingroup Elementary
   4  *
   5  * @addtogroup Video
   6  * @{
   7  *
   8  * @image html video_inheritance_tree.png
   9  * @image latex video_inheritance_tree.eps
  10  *
  11  * @image html player_inheritance_tree.png
  12  * @image latex player_inheritance_tree.eps
  13  *
  14  * Elementary comes with two object that help design application that need
  15  * to display video.
  16  *
  17  * The first one, Elm_Video, display a video by using Emotion.
  18  * It embeds the video inside an Edje object, so you can do some
  19  * animation depending on the video state change. It also implements a
  20  * resource management policy to remove this burden from the application.
  21  *
  22  * The second one,
  23  * Elm_Player is a video player that need to be linked with an Elm_Video.
  24  * It take care of updating its content according to Emotion event and provide a
  25  * way to theme itself. It also automatically raises the priority of the
  26  * linked Elm_Video so it will use the video decoder, if available. It also
  27  * activates the "remember" function on the linked Elm_Video object.
  28  *
  29  * Both widgets inherit from the @ref Layout one, so that all the
  30  * functions acting on it also work for video objects.
  31  *
  32  * The player widget emits the following signals, besides the ones
  33  * sent from @ref Layout:
  34  *  - @c "forward,clicked" - the user clicked the forward button.
  35  *  - @c "info,clicked" - the user clicked the info button.
  36  *  - @c "next,clicked" - the user clicked the next button.
  37  *  - @c "pause,clicked" - the user clicked the pause button.
  38  *  - @c "play,clicked" - the user clicked the play button.
  39  *  - @c "prev,clicked" - the user clicked the prev button.
  40  *  - @c "rewind,clicked" - the user clicked the rewind button.
  41  *  - @c "stop,clicked" - the user clicked the stop button.
  42  *
  43  * Default content parts of the player widget that you can use for are:
  44  * @li "video" - A video of the player
  45  *
  46  */
  47
  48 /**
  49  * @brief Add a new Elm_Player object to the given parent Elementary (container) object.
  50  *
  51  * @param parent The parent object
  52  * @return a new player widget handle or @c NULL, on errors.
  53  *
  54  * This function inserts a new player widget on the canvas.
  55  *
  56  * @see elm_object_part_content_set()
  57  *
  58  * @ingroup Video
  59  */
  60 EAPI Evas_Object         *elm_player_add(Evas_Object *parent);
  61
  62 /**
  63  * @brief Add a new Elm_Video object to the given parent Elementary (container) object.
  64  *
  65  * @param parent The parent object
  66  * @return a new video widget handle or @c NULL, on errors.
  67  *
  68  * This function inserts a new video widget on the canvas.
  69  *
  70  * @see elm_video_file_set()
  71  *
  72  * @ingroup Video
  73  */
  74 EAPI Evas_Object         *elm_video_add(Evas_Object *parent);
  75
  76 /**
  77  * @brief Define the file or URI that will be the video source.
  78  *
  79  * @param video The video object to define the file or URI for the video
  80  * of the Elm_Video object.
  81  *
  82  * @param filename The file or URI to target.
  83  * Local files can be specified using file:// or by using full file paths.
  84  * URI could be remote source of video, like http:// or local source like
  85  * WebCam (v4l2://). (You can use Emotion API to request and list
  86  * the available Webcam on your system).
  87  *
  88  * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
  89  *
  90  * This function will explicitly define a file or URI as a source
  91  * for the video of the Elm_Video object.
  92  *
  93  * @see elm_video_add()
  94  * @see elm_player_add()
  95  *
  96  * @ingroup Video
  97  */
  98 EAPI Eina_Bool            elm_video_file_set(Evas_Object *video, const char *filename);
  99
 100 /**
 101  * @brief Get the underlying Emotion object.
 102  *
 103  * @param video The video object to proceed the request on.
 104  * @return the underlying Emotion object.
 105  *
 106  * @ingroup Video
 107  */
 108 EAPI Evas_Object         *elm_video_emotion_get(const Evas_Object *video);
 109
 110 /**
 111  * @brief Start to play the video
 112  *
 113  * @param video The video object to proceed the request on.
 114  *
 115  * Start to play the video and cancel all suspend state.
 116  *
 117  * @ingroup Video
 118  */
 119 EAPI void                 elm_video_play(Evas_Object *video);
 120
 121 /**
 122  * @brief Pause the video
 123  *
 124  * @param video The video object to proceed the request on.
 125  *
 126  * Pause the video and start a timer to trigger suspend mode.
 127  *
 128  * @ingroup Video
 129  */
 130 EAPI void                 elm_video_pause(Evas_Object *video);
 131
 132 /**
 133  * @brief Stop the video
 134  *
 135  * @param video The video object to proceed the request on.
 136  *
 137  * Stop the video and put the emotion in deep sleep mode.
 138  *
 139  * @ingroup Video
 140  */
 141 EAPI void                 elm_video_stop(Evas_Object *video);
 142
 143 /**
 144  * @brief Is the video actually playing.
 145  *
 146  * @param video The video object to proceed the request on.
 147  * @return @c EINA_TRUE if the video is actually playing.
 148  *
 149  * You should consider watching event on the object instead of polling
 150  * the object state.
 151  *
 152  * @ingroup Video
 153  */
 154 EAPI Eina_Bool            elm_video_is_playing_get(const Evas_Object *video);
 155
 156 /**
 157  * @brief Is it possible to seek inside the video.
 158  *
 159  * @param video The video object to proceed the request on.
 160  * @return @c EINA_TRUE if is possible to seek inside the video.
 161  *
 162  * @ingroup Video
 163  */
 164 EAPI Eina_Bool            elm_video_is_seekable_get(const Evas_Object *video);
 165
 166 /**
 167  * @brief Is the audio muted.
 168  *
 169  * @param video The video object to proceed the request on.
 170  * @return @c EINA_TRUE if the audio is muted.
 171  *
 172  * @ingroup Video
 173  */
 174 EAPI Eina_Bool            elm_video_audio_mute_get(const Evas_Object *video);
 175
 176 /**
 177  * @brief Change the mute state of the Elm_Video object.
 178  *
 179  * @param video The video object to proceed the request on.
 180  * @param mute The new mute state.
 181  *
 182  * @ingroup Video
 183  */
 184 EAPI void                 elm_video_audio_mute_set(Evas_Object *video, Eina_Bool mute);
 185
 186 /**
 187  * @brief Get the audio level of the current video.
 188  *
 189  * @param video The video object to proceed the request on.
 190  * @return the current audio level.
 191  *
 192  * @ingroup Video
 193  */
 194 EAPI double               elm_video_audio_level_get(const Evas_Object *video);
 195
 196 /**
 197  * @brief Set the audio level of an Elm_Video object.
 198  *
 199  * @param video The video object to proceed the request on.
 200  * @param volume The new audio volume.
 201  *
 202  * @ingroup Video
 203  */
 204 EAPI void                 elm_video_audio_level_set(Evas_Object *video, double volume);
 205
 206 /**
 207  * @brief Get the current position (in seconds) being played in the
 208  * Elm_Video object.
 209  *
 210  * @param video The video object.
 211  * @return The time (in seconds) since the beginning of the media file.
 212  *
 213  * @ingroup Video
 214  */
 215 EAPI double               elm_video_play_position_get(const Evas_Object *video);
 216
 217 /**
 218  * @brief Set the current position (in seconds) to be played in the
 219  * Elm_Video object.
 220  *
 221  * @param video The video object.
 222  * @param position The time (in seconds) since the beginning of the media file.
 223  *
 224  * @ingroup Video
 225  */
 226 EAPI void                 elm_video_play_position_set(Evas_Object *video, double position);
 227 /**
 228  * @brief Get the total playing time (in seconds) of the Elm_Video object.
 229  *
 230  * @param video The video object.
 231  * @return The total duration (in seconds) of the media file.
 232  *
 233  * @ingroup Video
 234  */
 235 EAPI double               elm_video_play_length_get(const Evas_Object *video);
 236
 237 /**
 238  * @brief Set whether the object can remember the last played position.
 239  *
 240  * @param video The video object.
 241  * @param remember the last played position of the Elm_Video object.
 242  *
 243  * @note This API only serves as indication. System support is required.
 244  *
 245  * @ingroup Video
 246  */
 247 EAPI void                 elm_video_remember_position_set(Evas_Object *video, Eina_Bool remember);
 248
 249 /**
 250  * @brief Set whether the object can remember the last played position.
 251  *
 252  * @param video The video object.
 253  * @return whether the object remembers the last played position (@c EINA_TRUE)
 254  * or not.
 255  *
 256  * @note This API only serves as indication. System support is required.
 257  *
 258  * @ingroup Video
 259  */
 260 EAPI Eina_Bool            elm_video_remember_position_get(const Evas_Object *video);
 261
 262 /**
 263  * @brief Get the title (for instance DVD title) from this emotion object.
 264  *
 265  * @param video The Elm_Video object.
 266  * @return A string containing the title.
 267  *
 268  * This function is only useful when playing a DVD.
 269  *
 270  * @note Don't change or free the string returned by this function.
 271  *
 272  * @ingroup Video
 273  */
 274 EAPI const char          *elm_video_title_get(const Evas_Object *video);
 275 /**
 276  * @}
 277  */