src/lib/elm_video.h

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