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