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                 *elm_thumb_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
  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) EINA_ARG_NONNULL(1);
  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) EINA_ARG_NONNULL(1);
 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) EINA_ARG_NONNULL(1);
 127
 128    /**
 129     * Get the path and key to the image or video generated by ethumb.
 130     *
 131     * One just need 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) EINA_ARG_NONNULL(1);
 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 setting 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) EINA_ARG_NONNULL(1);
 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) EINA_ARG_NONNULL(1);
 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(void);
 229
 230    /**
 231     * Make the thumbnail 'editable'.
 232     *
 233     * @param obj Thumb object.
 234     * @param set 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) EINA_ARG_NONNULL(1);
 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) EINA_ARG_NONNULL(1);
 259
 260    /**
 261     * @}
 262     */
 263