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 DALI_IMPORT_API
  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 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   virtual ~NinePatchImage();
  87
  88   /**
  89    * @copydoc Dali::BaseHandle::operator=
  90    */
  91   using BaseHandle::operator=;
  92
  93   /**
  94    * Get the stretch borders
  95    * @return The border in pixels from the left, top, right, and bottom of the image respectively.
  96    */
  97   Vector4 GetStretchBorders();
  98
  99   /**
 100    * Get the child rectangle
 101    * @return the position and size of the child rectangle
 102    */
 103   Rect<int> GetChildRectangle();
 104
 105   /**
 106    * Creates a bitmap image from the bitmap with the 1 pixel border cropped off.
 107    * This does not change the internal bitmap.
 108    *
 109    * @return The cropped BitmapImage
 110    */
 111   BitmapImage CreateCroppedBitmapImage();
 112
 113 public: // Not intended for application developers
 114
 115   explicit DALI_INTERNAL NinePatchImage(Internal::NinePatchImage*);
 116 };
 117
 118 } // namespace Dali
 119
 120 #endif // __DALI_NINE_PATCH_IMAGE_H__