[dali_2.0.22] Merge branch 'devel/master'
[platform/core/uifw/dali-toolkit.git] / dali-toolkit / public-api / controls / image-view / image-view.h
1 #ifndef DALI_TOOLKIT_IMAGE_VIEW_H
2 #define DALI_TOOLKIT_IMAGE_VIEW_H
3
4 /*
5  * Copyright (c) 2020 Samsung Electronics Co., Ltd.
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License");
8  * you may not use this file except in compliance with the License.
9  * You may obtain a copy of the License at
10  *
11  * http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing, software
14  * distributed under the License is distributed on an "AS IS" BASIS,
15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16  * See the License for the specific language governing permissions and
17  * limitations under the License.
18  *
19  */
20
21 // INTERNAL INCLUDES
22 #include <dali-toolkit/public-api/controls/control.h>
23
24 // EXTERNAL INCLUDES
25 #include <dali/public-api/images/image-operations.h>
26
27 namespace Dali
28 {
29 namespace Toolkit
30 {
31 namespace Internal DALI_INTERNAL
32 {
33 class ImageView;
34 }
35 /**
36  * @addtogroup dali_toolkit_controls_image_view
37  * @{
38  */
39
40 /**
41  * @brief ImageView is a class for displaying an image resource.
42  *
43  * An instance of ImageView can be created using a URL or an Image instance.
44  *
45  * Some resources can be loaded before the ImageView is staged ( already cached ), in these cases if the connection to
46  * ResouceReadySignal is done after the resource is set then signal will be missed.
47  *
48  * To protect against this, IsResourceReady() can be checked before connecting to ResourceReadySignal,
49  * or the signal connection can be done before setting the resource.
50  *
51  * @code
52  *    auto myImageView = ImageView::New( resourceUrl );
53  *    if ( myImageView.IsResourceReady() )
54  *    {
55  *       // do something
56  *    }
57  *    else
58  *    {
59  *      myImageView.ResourceReadySignal.Connect( .... )
60  *    }
61  * @endcode
62  *
63  * OR Connect to signal before setting resource
64  *
65  * @code
66  *    auto myImageView = ImageView::New();
67  *    myImageView.ResourceReadySignal.Connect( .... )
68  *    myImageView.SetProperty( ImageView::Property::IMAGE, resourceUrl );
69  * @endcode
70  *
71  * @SINCE_1_0.0
72  *
73  */
74 class DALI_TOOLKIT_API ImageView : public Control
75 {
76 public:
77   /**
78    * @brief Enumeration for the start and end property ranges for this control.
79    * @SINCE_1_0.0
80    */
81   enum PropertyRange
82   {
83     PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1, ///< @SINCE_1_0.0
84     PROPERTY_END_INDEX   = PROPERTY_START_INDEX + 1000,             ///< Reserve property indices @SINCE_1_0.0
85
86     ANIMATABLE_PROPERTY_START_INDEX = ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX,       ///< @SINCE_1_1.18
87     ANIMATABLE_PROPERTY_END_INDEX   = ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX + 1000 ///< Reserve animatable property indices, @SINCE_1_1.18
88   };
89
90   /**
91    * @brief Enumeration for the instance of properties belonging to the ImageView class.
92    * @SINCE_1_0.0
93    */
94   struct Property
95   {
96     /**
97      * @brief Enumeration for the instance of properties belonging to the ImageView class.
98      * @SINCE_1_0.0
99      */
100     enum
101     {
102       // Event side properties
103
104       /**
105        * @brief name "image", type string if it is a url, map otherwise.
106        * @SINCE_1_0.0
107        */
108       IMAGE = PROPERTY_START_INDEX,
109
110       /**
111        * @brief name "preMultipliedAlpha", type Boolean.
112        * @SINCE_1_1.18
113        * @pre image must be initialized.
114        */
115       PRE_MULTIPLIED_ALPHA,
116
117       // Animatable properties
118
119       /**
120        * @brief name "pixelArea", type Vector4.
121        * @details Pixel area is a relative value with the whole image area as [0.0, 0.0, 1.0, 1.0].
122        * @SINCE_1_1.18
123        */
124       PIXEL_AREA = ANIMATABLE_PROPERTY_START_INDEX,
125     };
126   };
127
128 public:
129   /**
130    * @brief Creates an uninitialized ImageView.
131    * @SINCE_1_0.0
132    */
133   ImageView();
134
135   /**
136    * @brief Create an initialized ImageView.
137    *
138    * @SINCE_1_0.0
139    * @return A handle to a newly allocated Dali ImageView
140    *
141    * @note ImageView will not display anything.
142    */
143   static ImageView New();
144
145   /**
146    * @brief Creates an initialized ImageView from an URL to an image resource.
147    *
148    * If the string is empty, ImageView will not display anything.
149    *
150    * @SINCE_1_0.0
151    * @REMARK_INTERNET
152    * @REMARK_STORAGE
153    * @param[in] url The url of the image resource to display
154    * @return A handle to a newly allocated ImageView
155    */
156   static ImageView New(const std::string& url);
157
158   /**
159    * @brief Creates an initialized ImageView from a URL to an image resource.
160    *
161    * If the string is empty, ImageView will not display anything.
162    *
163    * @SINCE_1_1.10
164    * @REMARK_INTERNET
165    * @REMARK_STORAGE
166    * @param[in] url The url of the image resource to display
167    * @param [in] size The width and height to which to fit the loaded image
168    * @return A handle to a newly allocated ImageView
169    * @note A valid size is preferable for efficiency.
170    *       However, do not set a size that is bigger than the actual image size, as up-scaling is not available.
171    *       The content of the area not covered by the actual image is undefined and will not be cleared.
172    */
173   static ImageView New(const std::string& url, ImageDimensions size);
174
175   /**
176    * @brief Destructor.
177    *
178    * This is non-virtual since derived Handle types must not contain data or virtual methods.
179    * @SINCE_1_0.0
180    */
181   ~ImageView();
182
183   /**
184    * @brief Copy constructor.
185    *
186    * @SINCE_1_0.0
187    * @param[in] imageView ImageView to copy. The copied ImageView will point at the same implementation
188    */
189   ImageView(const ImageView& imageView);
190
191   /**
192    * @brief Move constructor
193    * @SINCE_1_9.23
194    *
195    * @param[in] rhs A reference to the moved handle
196    */
197   ImageView(ImageView&& rhs);
198
199   /**
200    * @brief Assignment operator.
201    *
202    * @SINCE_1_0.0
203    * @param[in] imageView The ImageView to assign from
204    * @return The updated ImageView
205    */
206   ImageView& operator=(const ImageView& imageView);
207
208   /**
209    * @brief Move assignment
210    * @SINCE_1_9.23
211    *
212    * @param[in] rhs A reference to the moved handle
213    * @return A reference to this
214    */
215   ImageView& operator=(ImageView&& rhs);
216
217   /**
218    * @brief Downcasts a handle to ImageView handle.
219    *
220    * If handle points to a ImageView, the downcast produces valid handle.
221    * If not, the returned handle is left uninitialized.
222    *
223    * @SINCE_1_0.0
224    * @param[in] handle Handle to an object
225    * @return Handle to a ImageView or an uninitialized handle
226    */
227   static ImageView DownCast(BaseHandle handle);
228
229   /**
230    * @brief Sets this ImageView from the given URL.
231    *
232    * If the URL is empty, ImageView will not display anything.
233    *
234    * @SINCE_1_1.4
235    * @REMARK_INTERNET
236    * @REMARK_STORAGE
237    * @param[in] url The URL to the image resource to display
238    */
239   void SetImage(const std::string& url);
240
241   /**
242    * @brief Sets this ImageView from the given URL.
243    *
244    * If the URL is empty, ImageView will not display anything.
245    *
246    * @SINCE_1_1.10
247    * @REMARK_INTERNET
248    * @REMARK_STORAGE
249    * @param[in] url The URL to the image resource to display
250    * @param [in] size The width and height to fit the loaded image to
251    */
252   void SetImage(const std::string& url, ImageDimensions size);
253
254 public: // Not intended for application developers
255   /// @cond internal
256   /**
257    * @brief Creates a handle using the Toolkit::Internal implementation.
258    *
259    * @SINCE_1_0.0
260    * @param[in] implementation The ImageView implementation
261    */
262   DALI_INTERNAL ImageView(Internal::ImageView& implementation);
263
264   /**
265    * @brief Allows the creation of this ImageView from an Internal::CustomActor pointer.
266    *
267    * @SINCE_1_0.0
268    * @param[in] internal A pointer to the internal CustomActor
269    */
270   DALI_INTERNAL ImageView(Dali::Internal::CustomActor* internal);
271   /// @endcond
272 };
273
274 /**
275  * @}
276  */
277 } // namespace Toolkit
278
279 } // namespace Dali
280
281 #endif // DALI_TOOLKIT_IMAGE_VIEW_H