src/lib/elm_thumb.h

   1 /**
   2  * @internal
   3  * @defgroup Thumb Thumbnail
   4  * @ingroup Elementary
   5  *
   6  * @image html thumb_inheritance_tree.png
   7  * @image latex thumb_inheritance_tree.eps
   8  *
   9  * @image html img/widget/thumb/preview-00.png
  10  * @image latex img/widget/thumb/preview-00.eps
  11  *
  12  * A thumbnail object is used for displaying the thumbnail of an image
  13  * or video. You must have compiled Elementary with @c Ethumb_Client
  14  * support. Also, Ethumb's DBus service must be present and
  15  * auto-activated in order to have thumbnails generated. You must also
  16  * have a @b session bus, not a @b system one.
  17  *
  18  * Once the thumbnail object becomes visible, it checks if there
  19  * is a previously generated thumbnail image for the file set on
  20  * it. If not, it starts generating this thumbnail.
  21  *
  22  * Different configuration settings causes different thumbnails to
  23  * be generated even on the same file.
  24  *
  25  * Generated thumbnails are stored under @c $HOME/.thumbnails/. Check
  26  * Ethumb's documentation to change this path, and to see other
  27  * configuration options.
  28  *
  29  * This widget emits the following signals:
  30  * - @c "clicked" - This is called when a user has clicked the
  31  *                  thumbnail object without dragging it around.
  32  * - @c "clicked,double" - This is called when a user has double-clicked
  33  *                         the thumbnail object.
  34  * - @c "press" - This is called when a user has pressed down over the
  35  *                thumbnail object.
  36  * - @c "generate,start" - The thumbnail generation has started.
  37  * - @c "generate,stop" - The generation process has stopped.
  38  * - @c "generate,error" - The thumbnail generation failed.
  39  * - @c "load,error" - The thumbnail image loading failed.
  40  *
  41  * Available styles:
  42  * - @c "default"
  43  * - @c "noframe"
  44  *
  45  * @{
  46  */
  47
  48 /**
  49  * @enum Elm_Thumb_Animation_Setting
  50  * @typedef Elm_Thumb_Animation_Setting
  51  *
  52  * @brief Enumeration to set if a video thumbnail is animating.
  53  *
  54  * @ingroup Thumb
  55  */
  56 typedef enum
  57 {
  58    ELM_THUMB_ANIMATION_START = 0, /**< Play animation once */
  59    ELM_THUMB_ANIMATION_LOOP, /**< Keep playing animation until stop is requested */
  60    ELM_THUMB_ANIMATION_STOP, /**< Stop playing the animation */
  61    ELM_THUMB_ANIMATION_LAST
  62 } Elm_Thumb_Animation_Setting;
  63
  64 /**
  65  * @brief Adds a new thumb object to the parent.
  66  *
  67  * @param[in] parent The parent object
  68  * @return The new object, otherwise @c NULL if it cannot be created
  69  *
  70  * @see elm_thumb_file_set()
  71  * @see elm_thumb_ethumb_client_get()
  72  *
  73  * @ingroup Thumb
  74  */
  75 EAPI Evas_Object                *elm_thumb_add(Evas_Object *parent);
  76
  77 /**
  78  * @brief Reloads a thumbnail if it is generated before.
  79  *
  80  * @remarks This is useful if the ethumb client configuration changed, like its
  81  *          size, aspect, or any other property one set in the handle returned
  82  *          by elm_thumb_ethumb_client_get().
  83  *
  84  * @remarks If the options didn't change, the thumbnail won't be generated again, but
  85  *          the old one is still used.
  86  *
  87  * @param[in] obj The thumb object to reload
  88  *
  89  * @see elm_thumb_file_set()
  90  *
  91  * @ingroup Thumb
  92  */
  93 EAPI void                        elm_thumb_reload(Evas_Object *obj);
  94
  95 /**
  96  * @brief Sets the file that is used as a thumbnail @b source.
  97  *
  98  * @remarks The file can be an image or a video (in that case, acceptable
  99  *          extensions are: avi, mp4, ogv, mov, mpg and wmv). To start the
 100  *          video animation, use the function elm_thumb_animate().
 101  *
 102  * @param[in] obj The thumb object
 103  * @param[in] file The path to the file that is used as a thumbnail source
 104  * @param[in] key The key used in case of an EET file
 105  *
 106  * @see elm_thumb_file_get()
 107  * @see elm_thumb_reload()
 108  * @see elm_thumb_animate()
 109  *
 110  * @ingroup Thumb
 111  */
 112 EAPI void                        elm_thumb_file_set(Evas_Object *obj, const char *file, const char *key);
 113
 114 /**
 115  * @brief Gets the image or video path and key used to generate the thumbnail.
 116  *
 117  * @param[in] obj The thumb object
 118  * @param[out] file A pointer to the filename
 119  * @param[out] key A pointer to the key
 120  *
 121  * @see elm_thumb_file_set()
 122  * @see elm_thumb_path_get()
 123  *
 124  * @ingroup Thumb
 125  */
 126 EAPI void                        elm_thumb_file_get(const Evas_Object *obj, const char **file, const char **key);
 127
 128 /**
 129  * @brief Gets the path and key to the image or video thumbnail generated by ethumb.
 130  *
 131  * @remarks One just needs to make sure that the thumbnail is generated before getting
 132  *          its path, otherwise the path is @c NULL. One way to do that is by asking
 133  *          for the path when/after the "generate,stop" smart callback is called.
 134  *
 135  * @param[in] obj The thumb object
 136  * @param[out] file A pointer to the thumb path
 137  * @param[out] key A pointer to the thumb key
 138  *
 139  * @see elm_thumb_file_get()
 140  *
 141  * @ingroup Thumb
 142  */
 143 EAPI void                        elm_thumb_path_get(const Evas_Object *obj, const char **file, const char **key);
 144
 145 /**
 146  * @brief Sets the animation state for the thumb object. If its content is an animated
 147  *        video, you may start/stop the animation or tell it to play continuously and
 148  *        looping.
 149  *
 150  * @param[in] obj The thumb object
 151  * @param[in] s The animation setting
 152  *
 153  * @see elm_thumb_file_set()
 154  *
 155  * @ingroup Thumb
 156  */
 157 EAPI void                        elm_thumb_animate_set(Evas_Object *obj, Elm_Thumb_Animation_Setting s);
 158
 159 /**
 160  * @brief Gets the animation state for the thumb object.
 161  *
 162  * @param[in] obj The thumb object
 163  * @return The animation setting, otherwise @c ELM_THUMB_ANIMATION_LAST
 164  *         on errors
 165  *
 166  * @see elm_thumb_animate_set()
 167  *
 168  * @ingroup Thumb
 169  */
 170 EAPI Elm_Thumb_Animation_Setting elm_thumb_animate_get(const Evas_Object *obj);
 171
 172 /**
 173  * @brief Gets the ethumb_client handle so that custom configuration can be made.
 174  *
 175  * @remarks This must be called before the objects are created to be sure that no object is
 176  *          visible and no generation has started.
 177  *
 178  * Example of usage:
 179  *
 180  * @code
 181  * #include <Elementary.h>
 182  * #ifndef ELM_LIB_QUICKLAUNCH
 183  * EAPI_MAIN int
 184  * elm_main(int argc, char **argv)
 185  * {
 186  *    Ethumb_Client *client;
 187  *
 188  *    elm_need_ethumb();
 189  *
 190  *    // ... your code
 191  *
 192  *    client = elm_thumb_ethumb_client_get();
 193  *    if (!client)
 194  *      {
 195  *         ERR("could not get ethumb_client");
 196  *         return 1;
 197  *      }
 198  *    ethumb_client_size_set(client, 100, 100);
 199  *    ethumb_client_crop_align_set(client, 0.5, 0.5);
 200  *    // ... your code
 201  *
 202  *    // Create elm_thumb objects here
 203  *
 204  *    elm_run();
 205  *    elm_shutdown();
 206  *    return 0;
 207  * }
 208  * #endif
 209  * ELM_MAIN()
 210  * @endcode
 211  *
 212  * @remarks There's only one client handle for Ethumb, so once a configuration
 213  *          change is done to it, any other request for thumbnails (for any thumbnail
 214  *          object) uses that configuration. Thus, this configuration is global.
 215  *
 216  * @return An Ethumb_Client instance, otherwise @c NULL
 217  *
 218  * @ingroup Thumb
 219  */
 220 EAPI void                       *elm_thumb_ethumb_client_get(void);
 221
 222 /**
 223  * @brief Gets the ethumb_client connection state.
 224  *
 225  * @return @c EINA_TRUE if the client is connected to the server, otherwise @c EINA_FALSE
 226  *
 227  */
 228 EAPI Eina_Bool                   elm_thumb_ethumb_client_connected_get(void);
 229
 230 /**
 231  * @brief Makes the thumbnail 'editable'.
 232  *
 233  * @remarks This means the thumbnail is a valid drag target for drag and drop, and can be
 234  *          cut or pasted.
 235  *
 236  * @param[in] obj The thumb object
 237  * @param[in] edit The boolean value that turns on or turns off editability \n
 238  *             Default is @c EINA_FALSE.
 239  *
 240  * @see elm_thumb_editable_get()
 241  *
 242  * @ingroup Thumb
 243  */
 244 EAPI Eina_Bool                   elm_thumb_editable_set(Evas_Object *obj, Eina_Bool edit);
 245
 246 /**
 247  * @brief Makes the thumbnail 'editable'.
 248  *
 249  * @remarks This means the thumbnail is a valid drag target for drag and drop, and can be
 250  *          cut or pasted.
 251  *
 252  * @param[in] obj The thumb object
 253  * @return The boolean value that turns on or turns off editability
 254  *
 255  * @see elm_thumb_editable_set()
 256  *
 257  * @ingroup Thumb
 258  */
 259 EAPI Eina_Bool                   elm_thumb_editable_get(const Evas_Object *obj);
 260
 261 /**
 262  * @}
 263  */