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