src/lib/elm_photocam.h

   1 /**
   2  * @defgroup Photocam Photocam
   3  * @ingroup Elementary
   4  *
   5  * @image html photocam_inheritance_tree.png
   6  * @image latex photocam_inheritance_tree.eps
   7  *
   8  * @image html img/widget/photocam/preview-00.png
   9  * @image latex img/widget/photocam/preview-00.eps
  10  *
  11  * Photocam is a widget meant specifically for displaying
  12  * high-resolution digital camera photos, giving speedy feedback (fast
  13  * load), zooming and panning as well as fitting logic, all with low
  14  * memory footprint. It is entirely focused on @b jpeg images, and
  15  * takes advantage of properties of the jpeg format (via Evas loader
  16  * features in the jpeg loader).
  17  *
  18  * Signals that you can add callbacks for are:
  19  * @li @c "clicked" - This is called when a user has clicked the photo
  20  *        without dragging around.
  21  * @li @c "press" - This is called when a user has pressed down on the
  22  *        photo.
  23  * @li @c "longpressed" - This is called when a user has pressed down
  24  *        on the photo for a long time without dragging around.
  25  * @li @c "clicked,double" - This is called when a user has
  26  *        double-clicked the photo.
  27  * @li @c "load" - Photo load begins.
  28  * @li @c "loaded" - This is called when the image file load is
  29  *        complete for the first view (low resolution blurry version).
  30  * @li @c "load,detail" - Photo detailed data load begins.
  31  * @li @c "loaded,detail" - This is called when the image file load is
  32  *        complete for the detailed image data (full resolution
  33  *        needed).
  34  * @li @c "zoom,start" - Zoom animation started.
  35  * @li @c "zoom,stop" - Zoom animation stopped.
  36  * @li @c "zoom,change" - Zoom changed when using an auto zoom mode.
  37  * @li @c "scroll" - the content has been scrolled (moved)
  38  * @li @c "scroll,anim,start" - scrolling animation has started
  39  * @li @c "scroll,anim,stop" - scrolling animation has stopped
  40  * @li @c "scroll,drag,start" - dragging the contents around has started
  41  * @li @c "scroll,drag,stop" - dragging the contents around has stopped
  42  *
  43  * This widget implements the @b @ref elm-scrollable-interface
  44  * interface, so that all (non-deprecated) functions for the base @ref
  45  * Scroller widget also work for photocam objects.
  46  *
  47  * Some calls on the photocam's API are marked as @b deprecated, as
  48  * they just wrap the scrollable widgets counterpart functions. Use
  49  * the ones we point you to, for each case of deprecation here,
  50  * instead -- eventually the deprecated ones will be discarded (next
  51  * major release).
  52  *
  53  * @ref tutorial_photocam shows the API in action.
  54  * @{
  55  */
  56
  57 /**
  58  * @brief Types of zoom available.
  59  */
  60 typedef enum
  61 {
  62    ELM_PHOTOCAM_ZOOM_MODE_MANUAL = 0, /**< Zoom controlled normally by elm_photocam_zoom_set */
  63    ELM_PHOTOCAM_ZOOM_MODE_AUTO_FIT, /**< Zoom until photo fits in photocam */
  64    ELM_PHOTOCAM_ZOOM_MODE_AUTO_FILL, /**< Zoom until photo fills photocam */
  65    ELM_PHOTOCAM_ZOOM_MODE_AUTO_FIT_IN, /**< Zoom in until photo fits in photocam */
  66    ELM_PHOTOCAM_ZOOM_MODE_LAST
  67 } Elm_Photocam_Zoom_Mode;
  68
  69 /**
  70  * @brief Add a new Photocam object
  71  *
  72  * @param parent The parent object
  73  * @return The new object or NULL if it cannot be created
  74  *
  75  * @ingroup Photocam
  76  */
  77 EAPI Evas_Object           *elm_photocam_add(Evas_Object *parent);
  78
  79 /**
  80  * @brief Set the photo file to be shown
  81  *
  82  * @param obj The photocam object
  83  * @param file The photo file
  84  * @return The return error (see EVAS_LOAD_ERROR_NONE, EVAS_LOAD_ERROR_GENERIC etc.)
  85  *
  86  * This sets (and shows) the specified file (with a relative or absolute
  87  * path) and will return a load error (same error that
  88  * evas_object_image_load_error_get() will return). The image will change and
  89  * adjust its size at this point and begin a background load process for this
  90  * photo that at some time in the future will be displayed at the full
  91  * quality needed.
  92  *
  93  * @ingroup Photocam
  94  */
  95 EAPI Evas_Load_Error        elm_photocam_file_set(Evas_Object *obj, const char *file);
  96
  97 /**
  98  * @brief Returns the path of the current image file
  99  *
 100  * @param obj The photocam object
 101  * @return Returns the path
 102  *
 103  * @see elm_photocam_file_set()
 104  *
 105  * @ingroup Photocam
 106  */
 107 EAPI const char            *elm_photocam_file_get(const Evas_Object *obj);
 108
 109 /**
 110  * @brief Set the zoom level of the photo
 111  *
 112  * @param obj The photocam object
 113  * @param zoom The zoom level to set
 114  *
 115  * This sets the zoom level. 1 will be 1:1 pixel for pixel. 2 will be 2:1
 116  * (that is 2x2 photo pixels will display as 1 on-screen pixel). 4:1 will be
 117  * 4x4 photo pixels as 1 screen pixel, and so on. The @p zoom parameter must
 118  * be greater than 0. It is suggested to stick to powers of 2. (1, 2, 4, 8,
 119  * 16, 32, etc.).
 120  *
 121  * @ingroup Photocam
 122  */
 123 EAPI void                   elm_photocam_zoom_set(Evas_Object *obj, double zoom);
 124
 125 /**
 126  * @brief Get the zoom level of the photo
 127  *
 128  * @param obj The photocam object
 129  * @return The current zoom level
 130  *
 131  * This returns the current zoom level of the photocam object. Note that if
 132  * you set the fill mode to other than ELM_PHOTOCAM_ZOOM_MODE_MANUAL
 133  * (which is the default), the zoom level may be changed at any time by the
 134  * photocam object itself to account for photo size and photocam viewport
 135  * size.
 136  *
 137  * @see elm_photocam_zoom_set()
 138  * @see elm_photocam_zoom_mode_set()
 139  *
 140  * @ingroup Photocam
 141  */
 142 EAPI double                 elm_photocam_zoom_get(const Evas_Object *obj);
 143
 144 /**
 145  * @brief Set the zoom mode
 146  *
 147  * @param obj The photocam object
 148  * @param mode The desired mode
 149  *
 150  * This sets the zoom mode to manual or one of several automatic levels.
 151  * Manual (ELM_PHOTOCAM_ZOOM_MODE_MANUAL) means that zoom is set manually by
 152  * elm_photocam_zoom_set() and will stay at that level until changed by code
 153  * or until zoom mode is changed. This is the default mode. The Automatic
 154  * modes will allow the photocam object to automatically adjust zoom mode
 155  * based on properties. ELM_PHOTOCAM_ZOOM_MODE_AUTO_FIT) will adjust zoom so
 156  * the photo fits EXACTLY inside the scroll frame with no pixels outside this
 157  * region. ELM_PHOTOCAM_ZOOM_MODE_AUTO_FILL will be similar but ensure no
 158  * pixels within the frame are left unfilled.
 159  *
 160  * @ingroup Photocam
 161  */
 162 EAPI void                   elm_photocam_zoom_mode_set(Evas_Object *obj, Elm_Photocam_Zoom_Mode mode);
 163
 164 /**
 165  * @brief Get the zoom mode
 166  *
 167  * @param obj The photocam object
 168  * @return The current zoom mode
 169  *
 170  * This gets the current zoom mode of the photocam object.
 171  *
 172  * @see elm_photocam_zoom_mode_set()
 173  *
 174  * @ingroup Photocam
 175  */
 176 EAPI Elm_Photocam_Zoom_Mode elm_photocam_zoom_mode_get(const Evas_Object *obj);
 177
 178 /**
 179  * @brief Get the current image pixel width and height
 180  *
 181  * @param obj The photocam object
 182  * @param w A pointer to the width return
 183  * @param h A pointer to the height return
 184  *
 185  * This gets the current photo pixel width and height (for the original).
 186  * The size will be returned in the integers @p w and @p h that are pointed
 187  * to.
 188  *
 189  * @ingroup Photocam
 190  */
 191 EAPI void                   elm_photocam_image_size_get(const Evas_Object *obj, int *w, int *h);
 192
 193 /**
 194  * @brief Get the region of the image that is currently shown
 195  *
 196  * @param obj
 197  * @param x A pointer to the X-coordinate of region
 198  * @param y A pointer to the Y-coordinate of region
 199  * @param w A pointer to the width
 200  * @param h A pointer to the height
 201  *
 202  * @see elm_photocam_image_region_show()
 203  * @see elm_photocam_image_region_bring_in()
 204  *
 205  * @ingroup Photocam
 206  */
 207 EAPI void                   elm_photocam_image_region_get(const Evas_Object *obj, int *x, int *y, int *w, int *h);
 208
 209 /**
 210  * @brief Set the viewed region of the image
 211  *
 212  * @param obj The photocam object
 213  * @param x X-coordinate of region in image original pixels
 214  * @param y Y-coordinate of region in image original pixels
 215  * @param w Width of region in image original pixels
 216  * @param h Height of region in image original pixels
 217  *
 218  * This shows the region of the image without using animation.
 219  *
 220  * @ingroup Photocam
 221  */
 222 EAPI void                   elm_photocam_image_region_show(Evas_Object *obj, int x, int y, int w, int h);
 223
 224 /**
 225  * @brief Bring in the viewed portion of the image
 226  *
 227  * @param obj The photocam object
 228  * @param x X-coordinate of region in image original pixels
 229  * @param y Y-coordinate of region in image original pixels
 230  * @param w Width of region in image original pixels
 231  * @param h Height of region in image original pixels
 232  *
 233  * This shows the region of the image using animation.
 234  *
 235  * @ingroup Photocam
 236  */
 237 EAPI void                   elm_photocam_image_region_bring_in(Evas_Object *obj, int x, int y, int w, int h);
 238
 239 /**
 240  * @brief Set the paused state for photocam
 241  *
 242  * @param obj The photocam object
 243  * @param paused The pause state to set
 244  *
 245  * This sets the paused state to on(EINA_TRUE) or off (EINA_FALSE) for
 246  * photocam. The default is off. This will stop zooming using animation on
 247  * zoom level changes and change instantly. This will stop any existing
 248  * animations that are running.
 249  *
 250  * @ingroup Photocam
 251  */
 252 EAPI void                   elm_photocam_paused_set(Evas_Object *obj, Eina_Bool paused);
 253
 254 /**
 255  * @brief Get the paused state for photocam
 256  *
 257  * @param obj The photocam object
 258  * @return The current paused state
 259  *
 260  * This gets the current paused state for the photocam object.
 261  *
 262  * @see elm_photocam_paused_set()
 263  *
 264  * @ingroup Photocam
 265  */
 266 EAPI Eina_Bool              elm_photocam_paused_get(const Evas_Object *obj);
 267
 268 /**
 269  * @brief Get the internal low-res image used for photocam
 270  *
 271  * @param obj The photocam object
 272  * @return The internal image object handle, or NULL if none exists
 273  *
 274  * This gets the internal image object inside photocam. Do not modify it. It
 275  * is for inspection only, and hooking callbacks to. Nothing else. It may be
 276  * deleted at any time as well.
 277  *
 278  * @ingroup Photocam
 279  */
 280 EAPI Evas_Object           *elm_photocam_internal_image_get(const Evas_Object *obj);
 281
 282 /**
 283  * @brief Set the photocam scrolling bouncing.
 284  *
 285  * @param obj The photocam object
 286  * @param h_bounce set this to @c EINA_TRUE for horizontal bouncing
 287  * @param v_bounce set this to @c EINA_TRUE for vertical bouncing
 288  *
 289  * @deprecated Use elm_scroller_bounce_set() instead.
 290  *
 291  * @ingroup Photocam
 292  */
 293 EINA_DEPRECATED EAPI void   elm_photocam_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce);
 294
 295 /**
 296  * @brief Get the photocam scrolling bouncing.
 297  *
 298  * @param obj The photocam object
 299  * @param h_bounce horizontal bouncing
 300  * @param v_bounce vertical bouncing
 301  *
 302  * @see elm_photocam_bounce_set()
 303  *
 304  * @deprecated Use elm_scroller_bounce_get() instead.
 305  *
 306  * @ingroup Photocam
 307  */
 308 EINA_DEPRECATED EAPI void   elm_photocam_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce);
 309
 310 /**
 311  * @brief Set the gesture state for photocam.
 312  *
 313  * @param obj The photocam object
 314  * @param gesture The gesture state to set
 315  *
 316  * This sets the gesture state to on(EINA_TRUE) or off (EINA_FALSE) for
 317  * photocam. The default is off. This will start multi touch zooming.
 318  *
 319  * @ingroup Photocam
 320  */
 321 EAPI void                  elm_photocam_gesture_enabled_set(Evas_Object *obj, Eina_Bool gesture);
 322
 323 /**
 324  * @brief Get the gesture state for photocam.
 325  *
 326  * @param obj The photocam object
 327  * @return The current gesture state
 328  *
 329  * This gets the current gesture state for the photocam object.
 330  *
 331  * @see elm_photocam_gesture_enabled_set()
 332  *
 333  * @ingroup Photocam
 334  */
 335 EAPI Eina_Bool             elm_photocam_gesture_enabled_get(const Evas_Object *obj);
 336 /**
 337  * @}
 338  */