src/lib/elm_thumb.h

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