src/lib/elm_thumb.h

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