dali/public-api/images/nine-patch-image.h

   1 #ifndef __DALI_NINE_PATCH_IMAGE_H__
   2 #define __DALI_NINE_PATCH_IMAGE_H__
   3
   4 /*
   5  * Copyright (c) 2015 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/public-api/images/resource-image.h>
  23 #include <dali/public-api/images/buffer-image.h>
  24 #include <dali/public-api/math/rect.h>
  25
  26 namespace Dali
  27 {
  28
  29 namespace Internal DALI_INTERNAL
  30 {
  31 class NinePatchImage;
  32 }
  33
  34
  35 /**
  36  * @brief NinePatchImage represents an image resource that can be added to ImageActors.
  37  * It contains a bitmap that is synchronously loaded from the file system that contains
  38  * a 9 patch border - a 1 pixel border that describes the stretch borders and the child
  39  * area.
  40  *
  41  * The class offers an API to read the stretch area and child area, but it does not
  42  * remove the border from it's bitmap. An API can be used to obtain a BufferImage with
  43  * the border removed.
  44  *
  45  * Adding this image to an ImageActor using an Image handle will automatically convert
  46  * to use the cropped BufferImage - if you don't retain a handle to this object, it will
  47  * be automatically destroyed.
  48  */
  49 class DALI_IMPORT_API NinePatchImage : public ResourceImage
  50 {
  51 public:
  52   /**
  53    * @brief Constructor which creates an uninitialized NinePatchImage object.
  54    *
  55    * Use Image::New(...) to create an initialised object.
  56    */
  57   NinePatchImage();
  58
  59   /**
  60    * @brief Create a new NinePatchImage.
  61    *
  62    * A pixel buffer for image data is allocated and loaded from the filesystem.
  63    * Dali has ownership of the buffer.
  64    * @note: default resource management policies are Immediate and Never
  65    *
  66    * @param [in] filename    File to load synchronously into buffer
  67    * @return a handle to a new instance of NinePatchImage
  68    */
  69   static NinePatchImage New( const std::string& filename );
  70
  71   /**
  72    * @brief Downcast an Object handle to NinePatchImage.
  73    *
  74    * If handle points to a NinePatchImage the downcast produces valid
  75    * handle. If not the returned handle is left uninitialized.
  76    *
  77    * @param[in] handle to An object
  78    * @return handle to a NinePatchImage or an uninitialized handle
  79    */
  80   static NinePatchImage DownCast( BaseHandle handle );
  81
  82   /**
  83    * @brief Destructor
  84    *
  85    * This is non-virtual since derived Handle types must not contain data or virtual methods.
  86    */
  87   ~NinePatchImage();
  88
  89   /**
  90    * @brief This copy constructor is required for (smart) pointer semantics.
  91    *
  92    * @param [in] handle A reference to the copied handle
  93    */
  94   NinePatchImage(const NinePatchImage& handle);
  95
  96   /**
  97    * @brief This assignment operator is required for (smart) pointer semantics.
  98    *
  99    * @param [in] rhs  A reference to the copied handle
 100    * @return A reference to this
 101    */
 102   NinePatchImage& operator=(const NinePatchImage& rhs);
 103
 104   /**
 105    * Get the stretch borders
 106    * @return The border in pixels from the left, top, right, and bottom of the image respectively.
 107    */
 108   Vector4 GetStretchBorders();
 109
 110   /**
 111    * Get the child rectangle
 112    * @return the position and size of the child rectangle
 113    */
 114   Rect<int> GetChildRectangle();
 115
 116   /**
 117    * Creates a buffer image from the bitmap with the 1 pixel border cropped off.
 118    * This does not change the internal bitmap.
 119    *
 120    * @return The cropped BufferImage
 121    */
 122   BufferImage CreateCroppedBufferImage();
 123
 124 public: // Not intended for application developers
 125
 126   explicit DALI_INTERNAL NinePatchImage(Internal::NinePatchImage*);
 127 };
 128
 129 } // namespace Dali
 130
 131 #endif // __DALI_NINE_PATCH_IMAGE_H__