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