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  * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
  79  *
  80  * This function will explicitly define a file or URI as a source
  81  * for the video of the Elm_Video object.
  82  *
  83  * @see elm_video_add()
  84  * @see elm_player_add()
  85  *
  86  * @ingroup Video
  87  */
  88 EAPI Eina_Bool            elm_video_file_set(Evas_Object *video, const char *filename);
  89
  90 /**
  91  * @brief Get the underlying Emotion object.
  92  *
  93  * @param video The video object to proceed the request on.
  94  * @return the underlying Emotion object.
  95  *
  96  * @ingroup Video
  97  */
  98 EAPI Evas_Object         *elm_video_emotion_get(const Evas_Object *video);
  99
 100 /**
 101  * @brief Start to play the video
 102  *
 103  * @param video The video object to proceed the request on.
 104  *
 105  * Start to play the video and cancel all suspend state.
 106  *
 107  * @ingroup Video
 108  */
 109 EAPI void                 elm_video_play(Evas_Object *video);
 110
 111 /**
 112  * @brief Pause the video
 113  *
 114  * @param video The video object to proceed the request on.
 115  *
 116  * Pause the video and start a timer to trigger suspend mode.
 117  *
 118  * @ingroup Video
 119  */
 120 EAPI void                 elm_video_pause(Evas_Object *video);
 121
 122 /**
 123  * @brief Stop the video
 124  *
 125  * @param video The video object to proceed the request on.
 126  *
 127  * Stop the video and put the emotion in deep sleep mode.
 128  *
 129  * @ingroup Video
 130  */
 131 EAPI void                 elm_video_stop(Evas_Object *video);
 132
 133 /**
 134  * @brief Is the video actually playing.
 135  *
 136  * @param video The video object to proceed the request on.
 137  * @return EINA_TRUE if the video is actually playing.
 138  *
 139  * You should consider watching event on the object instead of polling
 140  * the object state.
 141  *
 142  * @ingroup Video
 143  */
 144 EAPI Eina_Bool            elm_video_is_playing_get(const Evas_Object *video);
 145
 146 /**
 147  * @brief Is it possible to seek inside the video.
 148  *
 149  * @param video The video object to proceed the request on.
 150  * @return EINA_TRUE if is possible to seek inside the video.
 151  *
 152  * @ingroup Video
 153  */
 154 EAPI Eina_Bool            elm_video_is_seekable_get(const Evas_Object *video);
 155
 156 /**
 157  * @brief Is the audio muted.
 158  *
 159  * @param video The video object to proceed the request on.
 160  * @return EINA_TRUE if the audio is muted.
 161  *
 162  * @ingroup Video
 163  */
 164 EAPI Eina_Bool            elm_video_audio_mute_get(const Evas_Object *video);
 165
 166 /**
 167  * @brief Change the mute state of the Elm_Video object.
 168  *
 169  * @param video The video object to proceed the request on.
 170  * @param mute The new mute state.
 171  *
 172  * @ingroup Video
 173  */
 174 EAPI void                 elm_video_audio_mute_set(Evas_Object *video, Eina_Bool mute);
 175
 176 /**
 177  * @brief Get the audio level of the current video.
 178  *
 179  * @param video The video object to proceed the request on.
 180  * @return the current audio level.
 181  *
 182  * @ingroup Video
 183  */
 184 EAPI double               elm_video_audio_level_get(const Evas_Object *video);
 185
 186 /**
 187  * @brief Set the audio level of an Elm_Video object.
 188  *
 189  * @param video The video object to proceed the request on.
 190  * @param volume The new audio volume.
 191  *
 192  * @ingroup Video
 193  */
 194 EAPI void                 elm_video_audio_level_set(Evas_Object *video, double volume);
 195
 196 /**
 197  * @brief Get the current position (in seconds) being played in the
 198  * Elm_Video object.
 199  *
 200  * @param video The video object.
 201  * @return the time(in seconds) since the beginning of the media file.
 202  *
 203  * @ingroup Video
 204  */
 205 EAPI double               elm_video_play_position_get(const Evas_Object *video);
 206
 207 /**
 208  * @brief Set the current position (in seconds) to be played in the
 209  * Elm_Video object.
 210  *
 211  * @param video The video object.
 212  * @param position the time(in seconds) since the beginning of the media file.
 213  *
 214  * @ingroup Video
 215  */
 216 EAPI void                 elm_video_play_position_set(Evas_Object *video, double position);
 217 /**
 218  * @brief Get the total playing time (in seconds) of the Elm_Video object.
 219  *
 220  * @param video The video object.
 221  * @return the total duration(in seconds) of the media file.
 222  *
 223  * @ingroup Video
 224  */
 225 EAPI double               elm_video_play_length_get(const Evas_Object *video);
 226
 227 /**
 228  * @brief Set whether the object can remember the last played position.
 229  *
 230  * @param video The video object.
 231  * @param remember the last played position of the Elm_Video object.
 232  *
 233  * @note This API only serves as indication. System support is required.
 234  *
 235  * @ingroup Video
 236  */
 237 EAPI void                 elm_video_remember_position_set(Evas_Object *video, Eina_Bool remember);
 238
 239 /**
 240  * @brief Set whether the object can remember the last played position.
 241  *
 242  * @param video The video object.
 243  * @return whether the object remembers the last played position (EINA_TRUE)
 244  * or not.
 245  *
 246  * @note This API only serves as indication. System support is required.
 247  *
 248  * @ingroup Video
 249  */
 250 EAPI Eina_Bool            elm_video_remember_position_get(const Evas_Object *video);
 251
 252 /**
 253  * @brief Get the title (for ex. DVD title) from this emotion object.
 254  *
 255  * @param video The Elm_Video object.
 256  * @return A string containing the title.
 257  *
 258  * This function is only useful when playing a DVD.
 259  *
 260  * @note Don't change or free the string returned by this function.
 261  *
 262  * @ingroup Video
 263  */
 264 EAPI const char          *elm_video_title_get(const Evas_Object *video);
 265 /**
 266  * @}
 267  */