src/lib/elm_video.h

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