2 * @defgroup Photocam Photocam
5 * @image html photocam_inheritance_tree.png
6 * @image latex photocam_inheritance_tree.eps
8 * @image html img/widget/photocam/preview-00.png
9 * @image latex img/widget/photocam/preview-00.eps
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).
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
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
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
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.
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
53 * @ref tutorial_photocam shows the API in action.
58 * @brief Types of zoom available.
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;
70 * @brief Add a new Photocam object
72 * @param parent The parent object
73 * @return The new object or NULL if it cannot be created
77 EAPI Evas_Object *elm_photocam_add(Evas_Object *parent);
80 * @brief Set the photo file to be shown
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.)
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
95 EAPI Evas_Load_Error elm_photocam_file_set(Evas_Object *obj, const char *file);
98 * @brief Returns the path of the current image file
100 * @param obj The photocam object
101 * @return Returns the path
103 * @see elm_photocam_file_set()
107 EAPI const char *elm_photocam_file_get(const Evas_Object *obj);
110 * @brief Set the zoom level of the photo
112 * @param obj The photocam object
113 * @param zoom The zoom level to set
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,
123 EAPI void elm_photocam_zoom_set(Evas_Object *obj, double zoom);
126 * @brief Get the zoom level of the photo
128 * @param obj The photocam object
129 * @return The current zoom level
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
137 * @see elm_photocam_zoom_set()
138 * @see elm_photocam_zoom_mode_set()
142 EAPI double elm_photocam_zoom_get(const Evas_Object *obj);
145 * @brief Set the zoom mode
147 * @param obj The photocam object
148 * @param mode The desired mode
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.
162 EAPI void elm_photocam_zoom_mode_set(Evas_Object *obj, Elm_Photocam_Zoom_Mode mode);
165 * @brief Get the zoom mode
167 * @param obj The photocam object
168 * @return The current zoom mode
170 * This gets the current zoom mode of the photocam object.
172 * @see elm_photocam_zoom_mode_set()
176 EAPI Elm_Photocam_Zoom_Mode elm_photocam_zoom_mode_get(const Evas_Object *obj);
179 * @brief Get the current image pixel width and height
181 * @param obj The photocam object
182 * @param w A pointer to the width return
183 * @param h A pointer to the height return
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
191 EAPI void elm_photocam_image_size_get(const Evas_Object *obj, int *w, int *h);
194 * @brief Get the region of the image that is currently shown
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
202 * @see elm_photocam_image_region_show()
203 * @see elm_photocam_image_region_bring_in()
207 EAPI void elm_photocam_image_region_get(const Evas_Object *obj, int *x, int *y, int *w, int *h);
210 * @brief Set the viewed region of the image
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
218 * This shows the region of the image without using animation.
222 EAPI void elm_photocam_image_region_show(Evas_Object *obj, int x, int y, int w, int h);
225 * @brief Bring in the viewed portion of the image
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
233 * This shows the region of the image using animation.
237 EAPI void elm_photocam_image_region_bring_in(Evas_Object *obj, int x, int y, int w, int h);
240 * @brief Set the paused state for photocam
242 * @param obj The photocam object
243 * @param paused The pause state to set
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.
252 EAPI void elm_photocam_paused_set(Evas_Object *obj, Eina_Bool paused);
255 * @brief Get the paused state for photocam
257 * @param obj The photocam object
258 * @return The current paused state
260 * This gets the current paused state for the photocam object.
262 * @see elm_photocam_paused_set()
266 EAPI Eina_Bool elm_photocam_paused_get(const Evas_Object *obj);
269 * @brief Get the internal low-res image used for photocam
271 * @param obj The photocam object
272 * @return The internal image object handle, or NULL if none exists
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.
280 EAPI Evas_Object *elm_photocam_internal_image_get(const Evas_Object *obj);
283 * @brief Set the photocam scrolling bouncing.
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
289 * @deprecated Use elm_scroller_bounce_set() instead.
293 EINA_DEPRECATED EAPI void elm_photocam_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce);
296 * @brief Get the photocam scrolling bouncing.
298 * @param obj The photocam object
299 * @param h_bounce horizontal bouncing
300 * @param v_bounce vertical bouncing
302 * @see elm_photocam_bounce_set()
304 * @deprecated Use elm_scroller_bounce_get() instead.
308 EINA_DEPRECATED EAPI void elm_photocam_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce);
311 * @brief Set the gesture state for photocam.
313 * @param obj The photocam object
314 * @param gesture The gesture state to set
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.
321 EAPI void elm_photocam_gesture_enabled_set(Evas_Object *obj, Eina_Bool gesture);
324 * @brief Get the gesture state for photocam.
326 * @param obj The photocam object
327 * @return The current gesture state
329 * This gets the current gesture state for the photocam object.
331 * @see elm_photocam_gesture_enabled_set()
335 EAPI Eina_Bool elm_photocam_gesture_enabled_get(const Evas_Object *obj);