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.
  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 _Elm_Thumb_Animation_Setting
  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 *
  76                                  elm_thumb_add(Evas_Object *parent)
  77 EINA_ARG_NONNULL(1);
  78
  79 /**
  80  * Reload thumbnail if it was generated before.
  81  *
  82  * @param obj The thumb object to reload
  83  *
  84  * This is useful if the ethumb client configuration changed, like its
  85  * size, aspect or any other property one set in the handle returned
  86  * by elm_thumb_ethumb_client_get().
  87  *
  88  * If the options didn't change, the thumbnail won't be generated again, but
  89  * the old one will still be used.
  90  *
  91  * @see elm_thumb_file_set()
  92  *
  93  * @ingroup Thumb
  94  */
  95 EAPI void                        elm_thumb_reload(Evas_Object *obj) EINA_ARG_NONNULL(1);
  96
  97 /**
  98  * Set the file that will be used as thumbnail.
  99  *
 100  * @param obj The thumb object.
 101  * @param file The path to file that will be used as thumb.
 102  * @param key The key used in case of an EET file.
 103  *
 104  * The file can be an image or a video (in that case, acceptable extensions are:
 105  * avi, mp4, ogv, mov, mpg and wmv). To start the video animation, use the
 106  * function elm_thumb_animate().
 107  *
 108  * @see elm_thumb_file_get()
 109  * @see elm_thumb_reload()
 110  * @see elm_thumb_animate()
 111  *
 112  * @ingroup Thumb
 113  */
 114 EAPI void                        elm_thumb_file_set(Evas_Object *obj, const char *file, const char *key) EINA_ARG_NONNULL(1);
 115
 116 /**
 117  * Get the image or video path and key used to generate the thumbnail.
 118  *
 119  * @param obj The thumb object.
 120  * @param file Pointer to filename.
 121  * @param key Pointer to key.
 122  *
 123  * @see elm_thumb_file_set()
 124  * @see elm_thumb_path_get()
 125  *
 126  * @ingroup Thumb
 127  */
 128 EAPI void                        elm_thumb_file_get(const Evas_Object *obj, const char **file, const char **key) EINA_ARG_NONNULL(1);
 129
 130 /**
 131  * Get the path and key to the image or video generated by ethumb.
 132  *
 133  * One just need to make sure that the thumbnail was generated before getting
 134  * its path; otherwise, the path will be NULL. One way to do that is by asking
 135  * for the path when/after the "generate,stop" smart callback is called.
 136  *
 137  * @param obj The thumb object.
 138  * @param file Pointer to thumb path.
 139  * @param key Pointer to thumb key.
 140  *
 141  * @see elm_thumb_file_get()
 142  *
 143  * @ingroup Thumb
 144  */
 145 EAPI void                        elm_thumb_path_get(const Evas_Object *obj, const char **file, const char **key) EINA_ARG_NONNULL(1);
 146
 147 /**
 148  * Set the animation state for the thumb object. If its content is an animated
 149  * video, you may start/stop the animation or tell it to play continuously and
 150  * looping.
 151  *
 152  * @param obj The thumb object.
 153  * @param setting The animation setting.
 154  *
 155  * @see elm_thumb_file_set()
 156  *
 157  * @ingroup Thumb
 158  */
 159 EAPI void                        elm_thumb_animate_set(Evas_Object *obj, Elm_Thumb_Animation_Setting s) EINA_ARG_NONNULL(1);
 160
 161 /**
 162  * Get the animation state for the thumb object.
 163  *
 164  * @param obj The thumb object.
 165  * @return getting The animation setting or @c ELM_THUMB_ANIMATION_LAST,
 166  * on errors.
 167  *
 168  * @see elm_thumb_animate_set()
 169  *
 170  * @ingroup Thumb
 171  */
 172 EAPI Elm_Thumb_Animation_Setting elm_thumb_animate_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 173
 174 /**
 175  * Get the ethumb_client handle so custom configuration can be made.
 176  *
 177  * @return Ethumb_Client instance or NULL.
 178  *
 179  * This must be called before the objects are created to be sure no object is
 180  * visible and no generation started.
 181  *
 182  * Example of usage:
 183  *
 184  * @code
 185  * #include <Elementary.h>
 186  * #ifndef ELM_LIB_QUICKLAUNCH
 187  * EAPI_MAIN int
 188  * elm_main(int argc, char **argv)
 189  * {
 190  *    Ethumb_Client *client;
 191  *
 192  *    elm_need_ethumb();
 193  *
 194  *    // ... your code
 195  *
 196  *    client = elm_thumb_ethumb_client_get();
 197  *    if (!client)
 198  *      {
 199  *         ERR("could not get ethumb_client");
 200  *         return 1;
 201  *      }
 202  *    ethumb_client_size_set(client, 100, 100);
 203  *    ethumb_client_crop_align_set(client, 0.5, 0.5);
 204  *    // ... your code
 205  *
 206  *    // Create elm_thumb objects here
 207  *
 208  *    elm_run();
 209  *    elm_shutdown();
 210  *    return 0;
 211  * }
 212  * #endif
 213  * ELM_MAIN()
 214  * @endcode
 215  *
 216  * @note There's only one client handle for Ethumb, so once a configuration
 217  * change is done to it, any other request for thumbnails (for any thumbnail
 218  * object) will use that configuration. Thus, this configuration is global.
 219  *
 220  * @ingroup Thumb
 221  */
 222 EAPI void                       *elm_thumb_ethumb_client_get(void);
 223
 224 /**
 225  * Get the ethumb_client connection state.
 226  *
 227  * @return EINA_TRUE if the client is connected to the server or EINA_FALSE
 228  * otherwise.
 229  */
 230 EAPI Eina_Bool                   elm_thumb_ethumb_client_connected(void);
 231
 232 /**
 233  * Make the thumbnail 'editable'.
 234  *
 235  * @param obj Thumb object.
 236  * @param set Turn on or off editability. Default is @c EINA_FALSE.
 237  *
 238  * This means the thumbnail is a valid drag target for drag and drop, and can be
 239  * cut or pasted too.
 240  *
 241  * @see elm_thumb_editable_get()
 242  *
 243  * @ingroup Thumb
 244  */
 245 EAPI Eina_Bool                   elm_thumb_editable_set(Evas_Object *obj, Eina_Bool edit) EINA_ARG_NONNULL(1);
 246
 247 /**
 248  * Make the thumbnail 'editable'.
 249  *
 250  * @param obj Thumb object.
 251  * @return Editability.
 252  *
 253  * This means the thumbnail is a valid drag target for drag and drop, and can be
 254  * cut or pasted too.
 255  *
 256  * @see elm_thumb_editable_set()
 257  *
 258  * @ingroup Thumb
 259  */
 260 EAPI Eina_Bool                   elm_thumb_editable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 261
 262 /**
 263  * @}
 264  */