dali-toolkit/public-api/image-loader/async-image-loader.h

   1 #ifndef DALI_TOOLKIT_ASYNC_IMAGE_LOADER_H
   2 #define DALI_TOOLKIT_ASYNC_IMAGE_LOADER_H
   3
   4 /*
   5  * Copyright (c) 2018 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 // EXTERNAL INCLUDES
  21 #include <string>
  22 #include <dali/public-api/object/base-handle.h>
  23 #include <dali/public-api/images/image-operations.h>
  24 #include <dali/public-api/signals/dali-signal.h>
  25
  26 // INTERNAL INCLUDES
  27 #include <dali-toolkit/public-api/dali-toolkit-common.h>
  28
  29 namespace Dali
  30 {
  31 class PixelData;
  32
  33 namespace Toolkit
  34 {
  35
  36 namespace Internal DALI_INTERNAL
  37 {
  38 class AsyncImageLoader;
  39 }
  40
  41 /**
  42  * @brief The AsyncImageLoader is used to load pixel data from a URL asynchronously.
  43  *
  44  * The images are loaded in a worker thread to avoid blocking the main event thread.
  45  *
  46  * To keep track of the loading images, each load call is assigned an ID (which is returned by the Load() call).
  47  * To know when the Load has completed, connect to the ImageLoadedSignal.
  48  * This signal should be connected before Load is called (in case the signal is emitted immediately).
  49  *
  50  * Load errors can be detected by checking the PixelData object is valid from within the signal handler.
  51
  52  * Note: The PixelData object will automatically be destroyed when it leaves its scope.
  53  *
  54  * Example:
  55  *
  56  * @code
  57  * class MyClass : public ConnectionTracker
  58  * {
  59  *   public:
  60  *
  61  *   MyCallback( uint32_t loadedTaskId, PixelData pixelData )
  62  *   {
  63  *     // First check if the image loaded correctly.
  64  *     if( pixelData )
  65  *     {
  66  *       if( loadedTaskId == mId1 )
  67  *       {
  68  *         // use the loaded pixel data from the first image
  69  *       }
  70  *       else if( loadedTaskId == mId2 )
  71  *       {
  72  *         // use the loaded pixel data from the second image
  73  *       }
  74  *     }
  75  *   }
  76  *
  77  *   uint32_t mId1;
  78  *   uint32_t mId2;
  79  * };
  80  *
  81  * MyClass myObject;
  82  * AsyncImageLoader imageLoader = AsyncImageLoader::New();
  83  *
  84  * // Connect the signal here.
  85  * imageLoader.ImageLoadedSignal().Connect( &myObject, &MyClass::MyCallback );
  86  *
  87  * // Invoke the load calls (must do this after connecting the signal to guarantee callbacks occur).
  88  * myObject.mId1 = imageLoader.Load( "first_image_url.jpg" );
  89  * myObject.mId2 = imageLoader.Load( "second_image_url.jpg" );
  90  *
  91  * @endcode
  92  */
  93 class DALI_TOOLKIT_API AsyncImageLoader : public BaseHandle
  94 {
  95 public:
  96
  97   typedef Signal< void( uint32_t, PixelData ) > ImageLoadedSignalType; ///< Image loaded signal type @SINCE_1_2_14
  98
  99 public:
 100
 101   /**
 102    * @brief Constructor which creates an empty AsyncImageLoader handle.
 103    * @SINCE_1_2_14
 104    *
 105    * Use AsyncImageLoader::New() to create an initialised object.
 106    */
 107   AsyncImageLoader();
 108
 109   /**
 110    * @brief Destructor.
 111    * @SINCE_1_2_14
 112    *
 113    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 114    */
 115   ~AsyncImageLoader();
 116
 117   /**
 118    * @brief This copy constructor is required for (smart) pointer semantics.
 119    * @SINCE_1_2_14
 120    *
 121    * @param[in] handle A reference to the copied handle
 122    */
 123   AsyncImageLoader( const AsyncImageLoader& handle );
 124
 125   /**
 126    * @brief This assignment operator is required for (smart) pointer semantics.
 127    * @SINCE_1_2_14
 128    *
 129    * @param[in] handle  A reference to the copied handle
 130    * @return A reference to this
 131    */
 132   AsyncImageLoader& operator=( const AsyncImageLoader& handle );
 133
 134   /**
 135    * @brief Creates a new loader to load the image asynchronously in a worker thread.
 136    * @SINCE_1_2_14
 137    *
 138    * @return The image loader
 139    */
 140   static AsyncImageLoader New();
 141
 142   /**
 143    * @brief Downcasts a handle to AsyncImageLoader handle.
 144    *
 145    * If the handle points to an AsyncImageLoader object, the downcast produces a valid handle.
 146    * If not, the returned handle is left uninitialized.
 147    *
 148    * @SINCE_1_2_14
 149    * @param[in] handle A handle to an object
 150    * @return A handle to a AsyncImageLoader object or an uninitialized handle
 151    */
 152   static AsyncImageLoader DownCast( BaseHandle handle );
 153
 154   /**
 155    * @brief Starts an image loading task.
 156    * Note: When using this method, the following defaults will be used:
 157    * fittingMode = FittingMode::DEFAULT
 158    * samplingMode = SamplingMode::BOX_THEN_LINEAR
 159    * orientationCorrection = true
 160    *
 161    * @SINCE_1_2_14
 162    * @REMARK_INTERNET
 163    * @REMARK_STORAGE
 164    * @param[in] url The URL of the image file to load
 165    * @return The loading task id
 166    */
 167   uint32_t Load( const std::string& url );
 168
 169   /**
 170    * @brief Starts an image loading task.
 171    * Note: When using this method, the following defaults will be used:
 172    * fittingMode = FittingMode::DEFAULT
 173    * samplingMode = SamplingMode::BOX_THEN_LINEAR
 174    * orientationCorrection = true
 175    *
 176    * @SINCE_1_2_14
 177    * @REMARK_INTERNET
 178    * @REMARK_STORAGE
 179    * @param[in] url The URL of the image file to load
 180    * @param[in] dimensions The width and height to fit the loaded image to
 181    * @return The loading task id
 182    */
 183   uint32_t Load( const std::string& url, ImageDimensions dimensions );
 184
 185   /**
 186    * @brief Starts an image loading task.
 187    * @SINCE_1_2_14
 188    * @REMARK_INTERNET
 189    * @REMARK_STORAGE
 190    * @param[in] url The URL of the image file to load
 191    * @param[in] dimensions The width and height to fit the loaded image to
 192    * @param[in] fittingMode The method used to fit the shape of the image before loading to the shape defined by the size parameter
 193    * @param[in] samplingMode The filtering method used when sampling pixels from the input image while fitting it to desired size
 194    * @param[in] orientationCorrection Reorient the image to respect any orientation metadata in its header
 195    * @return The loading task id
 196    */
 197   uint32_t Load( const std::string& url,
 198                  ImageDimensions dimensions,
 199                  FittingMode::Type fittingMode,
 200                  SamplingMode::Type samplingMode,
 201                  bool orientationCorrection );
 202
 203   /**
 204    * @brief Cancels an image loading task if it is still queueing in the work thread.
 205    * @SINCE_1_2_14
 206    *
 207    * @param[in] loadingTaskId The task id returned when invoking the load call.
 208    * @return If true, the loading task is removed from the queue, otherwise the loading is already implemented and unable to cancel anymore
 209    */
 210   bool Cancel( uint32_t loadingTaskId );
 211
 212   /**
 213    * @brief Cancels all the loading tasks in the queue.
 214    * @SINCE_1_2_14
 215    */
 216   void CancelAll();
 217
 218   /**
 219    * @brief Signal emitted for connected callback functions to get access to the loaded pixel data.
 220    *
 221    * A callback of the following type may be connected:
 222    * @code
 223    *   void YourCallbackName( uint32_t id, PixelData pixelData );
 224    * @endcode
 225    * @SINCE_1_2_14
 226    * @return A reference to a signal object to Connect() with
 227    */
 228   ImageLoadedSignalType& ImageLoadedSignal();
 229
 230 public: // Not intended for developer use
 231
 232   /// @cond internal
 233   /**
 234    * @brief Allows the creation of a AsyncImageLoader handle from an internal pointer.
 235    *
 236    * @note Not intended for application developers
 237    * @SINCE_1_2_14
 238    * @param[in] impl A pointer to the object
 239    */
 240   explicit DALI_INTERNAL AsyncImageLoader( Internal::AsyncImageLoader* impl );
 241   /// @endcond
 242
 243 };
 244
 245 } // namespace Toolkit
 246
 247 } // namespace Dali
 248
 249 #endif // DALI_TOOLKIT_ASYNC_IMAGE_LOADER_H