dali-toolkit/devel-api/controls/alignment/alignment.h

   1 #ifndef DALI_ALIGNMENT_H
   2 #define DALI_ALIGNMENT_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 namespace Dali
  25 {
  26 namespace Toolkit
  27 {
  28 namespace Internal DALI_INTERNAL
  29 {
  30 class Alignment;
  31 }
  32 /**
  33  * @addtogroup dali_toolkit_controls_alignment
  34  * @{
  35  */
  36
  37 /**
  38  * @brief Alignment is a container which provides an easy way to align other actors inside its boundary.
  39  *
  40  * Additionally, it provides a scaling property to resize the contained actors @see Scaling.
  41  * @SINCE_1_0.0
  42  * @note The use of scaling property will override all constraints applied to actors.
  43  *
  44  * All actors added to an alignment are going to be set with the same anchor point and parent origin. And if the scaling property is set to a value
  45  * different than SCALE_NONE, constraints as well.
  46  */
  47 class DALI_TOOLKIT_API Alignment : public Control
  48 {
  49 public:
  50   /**
  51    * @brief Enumeration for different types of alignment.
  52    * @SINCE_1_0.0
  53    */
  54   enum Type
  55   {
  56     HORIZONTAL_LEFT   = 1,  ///< HORIZONTAL left alignment @SINCE_1_9.28
  57     HORIZONTAL_CENTER = 2,  ///< HORIZONTAL center alignment @SINCE_1_9.28
  58     HORIZONTAL_RIGHT  = 4,  ///< HORIZONTAL right alignment @SINCE_1_9.28
  59     VERTICAL_TOP      = 8,  ///< VERTICAL top alignment @SINCE_1_9.28
  60     VERTICAL_CENTER   = 16, ///< VERTICAL center alignment @SINCE_1_9.28
  61     VERTICAL_BOTTOM   = 32  ///< VERTICAL bottom alignment @SINCE_1_9.28
  62   };
  63
  64   /**
  65    * @brief Scaling determines how actors are scaled to match the alignment's boundary.
  66    * @SINCE_1_0.0
  67    */
  68   enum Scaling
  69   {
  70     SCALE_NONE,                ///< The original size is kept. @SINCE_1_9.28
  71     SCALE_TO_FILL,             ///< Scale added actors to fill alignment's boundary. Aspect ratio is not maintained. @SINCE_1_9.28
  72     SCALE_TO_FIT_KEEP_ASPECT,  ///< Scale added actors to fit within the alignment's boundary. Aspect ratio is maintained. @SINCE_1_9.28
  73     SCALE_TO_FILL_KEEP_ASPECT, ///< Scale added actors to fill the alignment's boundary. Aspect ratio is maintained, and the actor may exceed the alignment's boundary. @SINCE_1_9.28
  74     SHRINK_TO_FIT,             ///< If added actors are larger than the alignment's boundary it will be shrunk down to fit. Aspect ratio is not maintained @SINCE_1_9.28
  75     SHRINK_TO_FIT_KEEP_ASPECT, ///< If added actors are larger than the alignment's boundary it will be shrunk down to fit. Aspect ratio is maintained @SINCE_1_9.28
  76   };
  77
  78   /**
  79    * @brief Structure describing the padding values.
  80    * @SINCE_1_0.0
  81    */
  82   struct Padding
  83   {
  84     /**
  85      * @brief Constructor.
  86      * @SINCE_1_0.0
  87      */
  88     Padding()
  89     : left(0.f),
  90       right(0.f),
  91       top(0.f),
  92       bottom(0.f)
  93     {
  94     }
  95
  96     /**
  97      * @brief Constructor.
  98      *
  99      * @SINCE_1_0.0
 100      * @param[in] l Left padding
 101      * @param[in] r Right padding
 102      * @param[in] t Top padding
 103      * @param[in] b Bottom padding
 104      */
 105     Padding(float l, float r, float t, float b)
 106     : left(l),
 107       right(r),
 108       top(t),
 109       bottom(b)
 110     {
 111     }
 112
 113     float left;   ///< The left padding
 114     float right;  ///< The right padding
 115     float top;    ///< The top padding
 116     float bottom; ///< The bottom padding
 117   };
 118
 119   /**
 120    * @brief Creates an Alignment handle; this can be initialized with Alignment::New().
 121    *
 122    * Calling member functions with an uninitialized handle is not allowed.
 123    * @SINCE_1_0.0
 124    */
 125   Alignment();
 126
 127   /**
 128    * @brief Creates an alignment control.
 129    *
 130    * @SINCE_1_0.0
 131    * @param[in] horizontal Specifies how to align actors horizontally. Could be HORIZONTAL_LEFT, HORIZONTAL_CENTER or HORIZONTAL_RIGHT. By default, HORIZONTAL_CENTER
 132    * @param[in] vertical Specifies how to align actors vertically. Could be VERTICAL_TOP, VERTICAL_CENTER or VERTICAL_BOTTOM. By default, VERTICAL_CENTER
 133    * @return A handle to the Alignment control
 134    */
 135   static Alignment New(Type horizontal = HORIZONTAL_CENTER, Type vertical = VERTICAL_CENTER);
 136
 137   /**
 138    * @brief Copy constructor. Creates another handle that points to the same real object.
 139    *
 140    * @SINCE_1_0.0
 141    * @param[in] alignment Object to copy
 142    */
 143   Alignment(const Alignment& alignment);
 144
 145   /**
 146    * @brief Destructor.
 147    *
 148    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 149    * @SINCE_1_0.0
 150    */
 151   ~Alignment();
 152
 153   /**
 154    * @brief Downcasts a handle to Alignment handle.
 155    *
 156    * If handle points to an Alignment, the downcast produces valid handle.
 157    * If not, the returned handle is left uninitialized.
 158    *
 159    * @SINCE_1_0.0
 160    * @param[in] handle Handle to an object
 161    * @return A handle to a Alignment or an uninitialized handle
 162    */
 163   static Alignment DownCast(BaseHandle handle);
 164
 165   /**
 166    * @brief Sets the new alignment. By default, ( HORIZONTAL_CENTER | VERTICAL_CENTER ).
 167    *
 168    * @SINCE_1_0.0
 169    * @param[in] type The new alignment option
 170    * @note There should only be one horizontal and one vertical policy.
 171    */
 172   void SetAlignmentType(Type type);
 173
 174   /**
 175    * @brief Gets the current alignment combined into a single value.
 176    *
 177    * The values can be tested by using the & operator and the desired
 178    * flag. e.g.
 179    * @code
 180    *   if (GetAlignmentType() & HorizontalCentre)
 181    *   {
 182    *     ...
 183    *   }
 184    * @endcode
 185    *
 186    * @SINCE_1_0.0
 187    * @return the alignment value
 188    */
 189   Type GetAlignmentType() const;
 190
 191   /**
 192    * @brief Sets how added actors scale to fit the alignment's boundary.
 193    *
 194    * @SINCE_1_0.0
 195    * @param[in] scaling The scaling property
 196    * @see Scaling.
 197    */
 198   void SetScaling(Scaling scaling);
 199
 200   /**
 201    * @brief Retrieves the scaling property.
 202    *
 203    * @SINCE_1_0.0
 204    * @return The scaling
 205    * @see Scaling.
 206    */
 207   Scaling GetScaling() const;
 208
 209   /**
 210    * @brief Sets a padding value.
 211    *
 212    * @SINCE_1_0.0
 213    * @param[in] padding The left, right, top, bottom padding values
 214    */
 215   void SetPadding(const Padding& padding);
 216
 217   /**
 218    * @brief Gets the padding values.
 219    *
 220    * @SINCE_1_0.0
 221    * @return The left, right, top, bottom padding values
 222    */
 223   const Padding& GetPadding() const;
 224
 225   /**
 226    * @brief Assignment operator.
 227    *
 228    * Changes this handle to point to another real object.
 229    * @SINCE_1_0.0
 230    * @param[in] alignment Object to copy
 231    * @return A reference to this
 232    */
 233   Alignment& operator=(const Alignment& alignment);
 234
 235 public: // Not intended for application developers
 236   /// @cond internal
 237   /**
 238    * @brief Creates a handle using the Toolkit::Internal implementation.
 239    *
 240    * @SINCE_1_0.0
 241    * @param[in] implementation The Control implementation
 242    */
 243   DALI_INTERNAL Alignment(Internal::Alignment& implementation);
 244
 245   /**
 246    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 247    *
 248    * @SINCE_1_0.0
 249    * @param[in] internal A pointer to the internal CustomActor
 250    */
 251   explicit DALI_INTERNAL Alignment(Dali::Internal::CustomActor* internal);
 252   /// @endcond
 253 };
 254
 255 /**
 256  * @}
 257  */
 258
 259 } // namespace Toolkit
 260
 261 } // namespace Dali
 262
 263 #endif // DALI_ALIGNMENT_H