src/lib/elm_photocam.h

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