src/lib/elm_thumb.h

   1 /**
   2  * @defgroup Thumb Thumb
   3  *
   4  * @image html img/widget/thumb/preview-00.png
   5  * @image latex img/widget/thumb/preview-00.eps
   6  *
   7  * A thumb object is used for displaying the thumbnail of an image or video.
   8  * You must have compiled Elementary with Ethumb_Client support and the DBus
   9  * service must be present and auto-activated in order to have thumbnails to
  10  * be generated. You must also have a Session bus, not System bus.
  11  *
  12  * Once the thumbnail object becomes visible, it will check if there is a
  13  * previously generated thumbnail image for the file set on it. If not, it
  14  * will start generating this thumbnail.
  15  *
  16  * Different config settings will cause different thumbnails to be generated
  17  * even on the same file.
  18  *
  19  * Generated thumbnails are stored under @c $HOME/.thumbnails/. Check the
  20  * Ethumb documentation to change this path, and to see other configuration
  21  * options.
  22  *
  23  * Signals that you can add callbacks for are:
  24  *
  25  * - "clicked" - This is called when a user has clicked the thumb without dragging
  26  *             around.
  27  * - "clicked,double" - This is called when a user has double-clicked the thumb.
  28  * - "press" - This is called when a user has pressed down the thumb.
  29  * - "generate,start" - The thumbnail generation started.
  30  * - "generate,stop" - The generation process stopped.
  31  * - "generate,error" - The generation failed.
  32  * - "load,error" - The thumbnail image loading failed.
  33  *
  34  * available styles:
  35  * - default
  36  * - noframe
  37  *
  38  * An example of use of thumbnail:
  39  *
  40  * - @ref thumb_example_01
  41  */
  42
  43 /**
  44  * @addtogroup Thumb
  45  * @{
  46  */
  47
  48 /**
  49  * @enum _Elm_Thumb_Animation_Setting
  50  * @typedef Elm_Thumb_Animation_Setting
  51  *
  52  * Used to set if a video thumbnail is animating or not.
  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  * Add a new thumb object to the parent.
  66  *
  67  * @param parent The parent object.
  68  * @return The new object or 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  * Reload thumbnail if it was generated before.
  79  *
  80  * @param obj The thumb object to reload
  81  *
  82  * This is useful if the ethumb client configuration changed, like its
  83  * size, aspect or any other property one set in the handle returned
  84  * by elm_thumb_ethumb_client_get().
  85  *
  86  * If the options didn't change, the thumbnail won't be generated again, but
  87  * the old one will still be used.
  88  *
  89  * @see elm_thumb_file_set()
  90  *
  91  * @ingroup Thumb
  92  */
  93 EAPI void                        elm_thumb_reload(Evas_Object *obj);
  94
  95 /**
  96  * Set the file that will be used as thumbnail.
  97  *
  98  * @param obj The thumb object.
  99  * @param file The path to file that will be used as thumb.
 100  * @param key The key used in case of an EET file.
 101  *
 102  * The file can be an image or a video (in that case, acceptable extensions are:
 103  * avi, mp4, ogv, mov, mpg and wmv). To start the video animation, use the
 104  * function elm_thumb_animate().
 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  * Get the image or video path and key used to generate the thumbnail.
 116  *
 117  * @param obj The thumb object.
 118  * @param file Pointer to filename.
 119  * @param key Pointer to 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  * Get the path and key to the image or video thumbnail generated by ethumb.
 130  *
 131  * One just needs to make sure that the thumbnail was generated before getting
 132  * its path; otherwise, the path will be 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 obj The thumb object.
 136  * @param file Pointer to thumb path.
 137  * @param key Pointer to 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  * Set 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 obj The thumb object.
 151  * @param 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  * Get the animation state for the thumb object.
 161  *
 162  * @param obj The thumb object.
 163  * @return getting The animation setting or @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  * Get the ethumb_client handle so custom configuration can be made.
 174  *
 175  * @return Ethumb_Client instance or NULL.
 176  *
 177  * This must be called before the objects are created to be sure no object is
 178  * visible and no generation started.
 179  *
 180  * Example of usage:
 181  *
 182  * @code
 183  * #include <Elementary.h>
 184  * #ifndef ELM_LIB_QUICKLAUNCH
 185  * EAPI_MAIN int
 186  * elm_main(int argc, char **argv)
 187  * {
 188  *    Ethumb_Client *client;
 189  *
 190  *    elm_need_ethumb();
 191  *
 192  *    // ... your code
 193  *
 194  *    client = elm_thumb_ethumb_client_get();
 195  *    if (!client)
 196  *      {
 197  *         ERR("could not get ethumb_client");
 198  *         return 1;
 199  *      }
 200  *    ethumb_client_size_set(client, 100, 100);
 201  *    ethumb_client_crop_align_set(client, 0.5, 0.5);
 202  *    // ... your code
 203  *
 204  *    // Create elm_thumb objects here
 205  *
 206  *    elm_run();
 207  *    elm_shutdown();
 208  *    return 0;
 209  * }
 210  * #endif
 211  * ELM_MAIN()
 212  * @endcode
 213  *
 214  * @note There's only one client handle for Ethumb, so once a configuration
 215  * change is done to it, any other request for thumbnails (for any thumbnail
 216  * object) will use that configuration. Thus, this configuration is global.
 217  *
 218  * @ingroup Thumb
 219  */
 220 EAPI void                       *elm_thumb_ethumb_client_get(void);
 221
 222 /**
 223  * Get the ethumb_client connection state.
 224  *
 225  * @return EINA_TRUE if the client is connected to the server or EINA_FALSE
 226  * otherwise.
 227  */
 228 EAPI Eina_Bool                   elm_thumb_ethumb_client_connected_get(void);
 229
 230 /**
 231  * Make the thumbnail 'editable'.
 232  *
 233  * @param obj Thumb object.
 234  * @param edit Turn on or off editability. Default is @c EINA_FALSE.
 235  *
 236  * This means the thumbnail is a valid drag target for drag and drop, and can be
 237  * cut or pasted too.
 238  *
 239  * @see elm_thumb_editable_get()
 240  *
 241  * @ingroup Thumb
 242  */
 243 EAPI Eina_Bool                   elm_thumb_editable_set(Evas_Object *obj, Eina_Bool edit);
 244
 245 /**
 246  * Make the thumbnail 'editable'.
 247  *
 248  * @param obj Thumb object.
 249  * @return Editability.
 250  *
 251  * This means the thumbnail is a valid drag target for drag and drop, and can be
 252  * cut or pasted too.
 253  *
 254  * @see elm_thumb_editable_set()
 255  *
 256  * @ingroup Thumb
 257  */
 258 EAPI Eina_Bool                   elm_thumb_editable_get(const Evas_Object *obj);
 259
 260 /**
 261  * @}
 262  */