dali-toolkit/devel-api/layouting/flex-node.h

   1 #ifndef DALI_TOOLKIT_LAYOUTING_FLEX_NODE_H
   2 #define DALI_TOOLKIT_LAYOUTING_FLEX_NODE_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 // EXTERNAL INCLUDES
  21 #include <dali/public-api/actors/actor.h>
  22 #include <dali/public-api/common/dali-common.h>
  23 #include <memory>
  24
  25 // INTERNAL INCLUDES
  26 #include <dali-toolkit/public-api/dali-toolkit-common.h>
  27
  28 namespace Dali
  29 {
  30 namespace Toolkit
  31 {
  32 namespace Flex
  33 {
  34 class Node;
  35
  36 /**
  37  * @brief Enumeration for the direction of the main axis in the flex container. This determines
  38  * the direction that flex items are laid out in the flex container.
  39  */
  40 enum class FlexDirection
  41 {
  42   COLUMN,         ///< The flexible items are displayed vertically as a column
  43   COLUMN_REVERSE, ///< The flexible items are displayed vertically as a column, but in reverse order
  44   ROW,            ///< The flexible items are displayed horizontally as a row
  45   ROW_REVERSE     ///< The flexible items are displayed horizontally as a row, but in reverse order
  46 };
  47
  48 /**
  49  * @brief Enumeration for the alignment of the flex items when the items do not use all available
  50  * space on the main-axis.
  51  */
  52 enum class Justification
  53 {
  54   FLEX_START,    ///< Items are positioned at the beginning of the container
  55   CENTER,        ///< Items are positioned at the center of the container
  56   FLEX_END,      ///< Items are positioned at the end of the container
  57   SPACE_BETWEEN, ///< Items are positioned with equal space between the items
  58   SPACE_AROUND   ///< Items are positioned with equal space before, between, and after the items
  59 };
  60
  61 /**
  62  * @brief Enumeration for the wrap type of the flex container when there is not enough room for
  63  * all the items on one flex line.
  64  */
  65 enum class WrapType
  66 {
  67   NO_WRAP, ///< Flex items laid out in single line (shrunk to fit the flex container along the main axis)
  68   WRAP     ///< Flex items laid out in multiple lines if needed
  69 };
  70
  71 /**
  72  * @brief Enumeration for the alignment of the flex items or lines when the items or lines do not
  73  * use all the available space on the cross-axis.
  74  */
  75 enum class Alignment
  76 {
  77   AUTO, ///< Currently unsupported, placeholder for inheritance of parent alignment.
  78
  79   FLEX_START, ///< At the beginning of the container
  80   CENTER,     ///< At the center of the container
  81   FLEX_END,   ///< At the end of the container
  82   STRETCH     ///< Stretch to fit the container
  83 };
  84
  85 /**
  86  * @brief Enumeration for the position type of the flex item how it is positioned within its parent.
  87  */
  88 enum class PositionType
  89 {
  90   RELATIVE, ///< Flex items laid out relatively
  91   ABSOLUTE  ///< Flex items laid out absolutely
  92 };
  93
  94 /**
  95  * Struct used for MeasureCallback
  96  */
  97 struct SizeTuple
  98 {
  99   SizeTuple(float x, float y)
 100   : width(x),
 101     height(y)
 102   {
 103   }
 104
 105   float width;
 106   float height;
 107 };
 108
 109 /**
 110  * @brief Callback signature for child Actor measure callback.
 111  * @note Actor, child Actor to measure
 112  * @note float, available width for child
 113  * @note int, width measure specifcation mode
 114  * @note float, available height for child
 115  * @note int, height measure specification mode
 116  */
 117 using MeasureCallback = SizeTuple (*)(Dali::Actor, float, int, float, int);
 118
 119 /**
 120  * This class provides the API for calling into the Flex layout implementation.
 121  */
 122 class DALI_TOOLKIT_API Node
 123 {
 124 public:
 125   /**
 126    * @brief Constructor.
 127    */
 128   Node();
 129
 130   /**
 131    * @brief Destructor.
 132    */
 133   ~Node();
 134
 135   Node& operator=(Node&&) = default;
 136   Node(Node&&)            = default;
 137   Node(const Node&)       = delete;
 138   Node& operator=(const Node&) = delete;
 139
 140   /**
 141    * @brief Insert child into the FlexLayout at the given index.
 142    * @param[in] child Actor to insert.
 143    * @param[in] margin of child Actor.
 144    * @param[in] measureFunction for the child.
 145    * @param[in] index to insert at.
 146    * @return child node pointer
 147    */
 148   Node* AddChild(Actor child, Extents margin, MeasureCallback measureFunction, int index);
 149
 150   /**
 151    * @brief Remove child from the FlexLayout at the given index.
 152    * @param[in] child child to be removed.
 153    */
 154   void RemoveChild(Actor child);
 155
 156   /**
 157    * @brief Return the dimensions of the node.
 158    * @param[in] width width specification
 159    * @param[in] widthMode width specification mode
 160    * @param[in] height height specification
 161    * @param[in] heightMode height specification mode
 162    * @return Size tuple representing the width and height of the node
 163    */
 164   SizeTuple MeasureNode(float width, int widthMode, float height, int heightMode);
 165
 166   /**
 167    * @brief Perform the layout measure calculations.
 168    * @param[in] availableWidth Amount of space available for layout, width.
 169    * @param[in] availableHeight Amount of space available for layout, height.
 170    * @param[in] isRTL Is the direction of the layout right to left.
 171    */
 172   void CalculateLayout(float availableWidth, float availableHeight, bool isRTL);
 173
 174   /**
 175    * @brief Get the calculated width of the given node.
 176    * @return the width of the node
 177    */
 178   float GetFlexWidth() const;
 179
 180   /**
 181    * @brief Get the calculated height of the given node.
 182    * @return the height of the node
 183    */
 184   float GetFlexHeight() const;
 185
 186   /**
 187    * @brief Get frame coordinates of the node at the given index.
 188    * @param[in] index of the child
 189    * @return Frame structure left x, top y, right z, bottom w
 190    */
 191   Vector4 GetNodeFrame(int index) const;
 192
 193   /**
 194    * @brief Set the flex direction in the layout.
 195    * The direction of the main-axis which determines the direction that flex items are laid out.
 196    * @param[in] flexDirection The flex direction.
 197    */
 198   void SetFlexDirection(FlexDirection flexDirection);
 199
 200   /**
 201    * @brief Get the flex direction in the layout.
 202    * @return The flex direction.
 203    */
 204   FlexDirection GetFlexDirection() const;
 205
 206   /**
 207    * @brief Set the justification in the layout.
 208    * @param[in] flexJustification The flex justification.
 209    */
 210   void SetFlexJustification(Justification flexJustification);
 211
 212   /**
 213    * @brief Get the flex justification in the layout.
 214    * @return The flex justification.
 215    */
 216   Justification GetFlexJustification() const;
 217
 218   /**
 219    * @brief Set the wrap in the layout.
 220    * @param[in] flexWrap The flex wrap.
 221    */
 222   void SetFlexWrap(WrapType flexWrap);
 223
 224   /**
 225    * @brief Get the flex wrap in the layout.
 226    * @return The flex wrap.
 227    */
 228   WrapType GetFlexWrap() const;
 229
 230   /**
 231    * @brief Set the alignment of the layout content.
 232    * @param[in] flexAlignment The alignment of the content.
 233    */
 234   void SetFlexAlignment(Alignment flexAlignment);
 235
 236   /**
 237    * @brief Get the alignment of the layout content.
 238    * @return The flex content alignment.
 239    */
 240   Alignment GetFlexAlignment() const;
 241
 242   /**
 243    * @brief Set the alignment of the layout items.
 244    * @param[in] flexAlignment The alignment of the items.
 245    */
 246   void SetFlexItemsAlignment(Alignment flexAlignment);
 247
 248   /**
 249    * @brief Get the alignment of the layout items.
 250    * @return The flex items alignment.
 251    */
 252   Alignment GetFlexItemsAlignment() const;
 253
 254   /**
 255    * @brief Set the alignment self of the layout items.
 256    * @param[in] flexAlignmentSelf The alignment self of the items.
 257    */
 258   void SetFlexAlignmentSelf(Alignment flexAlignmentSelf);
 259
 260   /**
 261    * @brief Get the alignment self of the layout items.
 262    * @return The flex items alignment self.
 263    */
 264   Alignment GetFlexAlignmentSelf() const;
 265
 266   /**
 267    * @brief Set the position type of the layout items.
 268    * @param[in] flexPositionType The position type of the items.
 269    */
 270   void SetFlexPositionType(PositionType flexPositionType);
 271
 272   /**
 273    * @brief Get the position type of the layout items.
 274    * @return The flex position type.
 275    */
 276   PositionType GetFlexPositionType() const;
 277
 278   /**
 279    * @brief Set the aspect ratio of the layout items.
 280    * @param[in] flexAspectRatio The aspect ratio of the items.
 281    */
 282   void SetFlexAspectRatio(float flexAspectRatio);
 283
 284   /**
 285    * @brief Get the aspect ratio of the layout items.
 286    * @return The flex aspect ratio.
 287    */
 288   float GetFlexAspectRatio() const;
 289
 290   /**
 291    * @brief Set the basis of the layout items.
 292    * @param[in] flexBasis The basis of the items.
 293    */
 294   void SetFlexBasis(float flexBasis);
 295
 296   /**
 297    * @brief Get the basis of the layout items.
 298    * @return The flex basis.
 299    */
 300   float GetFlexBasis() const;
 301
 302   /**
 303    * @brief Set the shrink of the layout items.
 304    * @param[in] flexShrink The shrink of the items.
 305    */
 306   void SetFlexShrink(float flexShrink);
 307
 308   /**
 309    * @brief Get the shrink of the layout items.
 310    * @return The flex shrink.
 311    */
 312   float GetFlexShrink() const;
 313
 314   /**
 315    * @brief Set the grow of the layout items.
 316    * @param[in] flexGrow The grow of the items.
 317    */
 318   void SetFlexGrow(float flexGrow);
 319
 320   /**
 321    * @brief Get the grow of the layout items.
 322    * @return The flex grow.
 323    */
 324   float GetFlexGrow() const;
 325
 326   /**
 327    * @brief Set the margin.
 328    * @param[in] margin The margin value.
 329    */
 330   void SetMargin(Extents margin);
 331
 332   /**
 333    * @brief Set the padding.
 334    * @param[in] padding The padding value.
 335    */
 336   void SetPadding(Extents padding);
 337
 338 private:
 339   struct Impl;
 340   std::unique_ptr<Impl> mImpl;
 341
 342 }; // Node
 343
 344 } // namespace Flex
 345 } // namespace Toolkit
 346 } // namespace Dali
 347
 348 #endif // DALI_TOOLKIT_LAYOUTING_FLEX_NODE_H