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  * @note SizeTuple, return value
 117  */
 118 using MeasureCallback = void (*)(Dali::Actor, float , int , float , int, SizeTuple *);
 119
 120 /**
 121  * This class provides the API for calling into the Flex layout implementation.
 122  */
 123 class DALI_TOOLKIT_API Node
 124 {
 125 public:
 126   /**
 127    * @brief Constructor.
 128    */
 129   Node();
 130
 131   /**
 132    * @brief Destructor.
 133    */
 134   ~Node();
 135
 136   Node& operator=(Node&&) = default;
 137   Node(Node&&)            = default;
 138   Node(const Node&)       = delete;
 139   Node& operator=(const Node&) = delete;
 140
 141   /**
 142    * @brief Insert child into the FlexLayout at the given index.
 143    * @param[in] child Actor to insert.
 144    * @param[in] margin of child Actor.
 145    * @param[in] measureFunction for the child.
 146    * @param[in] index to insert at.
 147    * @return child node pointer
 148    */
 149   Node* AddChild(Actor child, Extents margin, MeasureCallback measureFunction, int index);
 150
 151   /**
 152    * @brief Remove child from the FlexLayout at the given index.
 153    * @param[in] child child to be removed.
 154    */
 155   void RemoveChild(Actor child);
 156
 157   /**
 158    * @brief Return the dimensions of the node.
 159    * @param[in] width width specification
 160    * @param[in] widthMode width specification mode
 161    * @param[in] height height specification
 162    * @param[in] heightMode height specification mode
 163    * @return Size tuple representing the width and height of the node
 164    */
 165   SizeTuple MeasureNode(float width, int widthMode, float height, int heightMode);
 166
 167   /**
 168    * @brief Perform the layout measure calculations.
 169    * @param[in] availableWidth Amount of space available for layout, width.
 170    * @param[in] availableHeight Amount of space available for layout, height.
 171    * @param[in] isRTL Is the direction of the layout right to left.
 172    */
 173   void CalculateLayout(float availableWidth, float availableHeight, bool isRTL);
 174
 175   /**
 176    * @brief Get the calculated width of the given node.
 177    * @return the width of the node
 178    */
 179   float GetFlexWidth() const;
 180
 181   /**
 182    * @brief Get the calculated height of the given node.
 183    * @return the height of the node
 184    */
 185   float GetFlexHeight() const;
 186
 187   /**
 188    * @brief Get frame coordinates of the node at the given index.
 189    * @param[in] index of the child
 190    * @return Frame structure left x, top y, right z, bottom w
 191    */
 192   Vector4 GetNodeFrame(int index) const;
 193
 194   /**
 195    * @brief Set the flex direction in the layout.
 196    * The direction of the main-axis which determines the direction that flex items are laid out.
 197    * @param[in] flexDirection The flex direction.
 198    */
 199   void SetFlexDirection(FlexDirection flexDirection);
 200
 201   /**
 202    * @brief Get the flex direction in the layout.
 203    * @return The flex direction.
 204    */
 205   FlexDirection GetFlexDirection() const;
 206
 207   /**
 208    * @brief Set the justification in the layout.
 209    * @param[in] flexJustification The flex justification.
 210    */
 211   void SetFlexJustification(Justification flexJustification);
 212
 213   /**
 214    * @brief Get the flex justification in the layout.
 215    * @return The flex justification.
 216    */
 217   Justification GetFlexJustification() const;
 218
 219   /**
 220    * @brief Set the wrap in the layout.
 221    * @param[in] flexWrap The flex wrap.
 222    */
 223   void SetFlexWrap(WrapType flexWrap);
 224
 225   /**
 226    * @brief Get the flex wrap in the layout.
 227    * @return The flex wrap.
 228    */
 229   WrapType GetFlexWrap() const;
 230
 231   /**
 232    * @brief Set the alignment of the layout content.
 233    * @param[in] flexAlignment The alignment of the content.
 234    */
 235   void SetFlexAlignment(Alignment flexAlignment);
 236
 237   /**
 238    * @brief Get the alignment of the layout content.
 239    * @return The flex content alignment.
 240    */
 241   Alignment GetFlexAlignment() const;
 242
 243   /**
 244    * @brief Set the alignment of the layout items.
 245    * @param[in] flexAlignment The alignment of the items.
 246    */
 247   void SetFlexItemsAlignment(Alignment flexAlignment);
 248
 249   /**
 250    * @brief Get the alignment of the layout items.
 251    * @return The flex items alignment.
 252    */
 253   Alignment GetFlexItemsAlignment() const;
 254
 255   /**
 256    * @brief Set the alignment self of the layout items.
 257    * @param[in] flexAlignmentSelf The alignment self of the items.
 258    */
 259   void SetFlexAlignmentSelf(Alignment flexAlignmentSelf);
 260
 261   /**
 262    * @brief Get the alignment self of the layout items.
 263    * @return The flex items alignment self.
 264    */
 265   Alignment GetFlexAlignmentSelf() const;
 266
 267   /**
 268    * @brief Set the position type of the layout items.
 269    * @param[in] flexPositionType The position type of the items.
 270    */
 271   void SetFlexPositionType(PositionType flexPositionType);
 272
 273   /**
 274    * @brief Get the position type of the layout items.
 275    * @return The flex position type.
 276    */
 277   PositionType GetFlexPositionType() const;
 278
 279   /**
 280    * @brief Set the aspect ratio of the layout items.
 281    * @param[in] flexAspectRatio The aspect ratio of the items.
 282    */
 283   void SetFlexAspectRatio(float flexAspectRatio);
 284
 285   /**
 286    * @brief Get the aspect ratio of the layout items.
 287    * @return The flex aspect ratio.
 288    */
 289   float GetFlexAspectRatio() const;
 290
 291   /**
 292    * @brief Set the basis of the layout items.
 293    * @param[in] flexBasis The basis of the items.
 294    */
 295   void SetFlexBasis(float flexBasis);
 296
 297   /**
 298    * @brief Get the basis of the layout items.
 299    * @return The flex basis.
 300    */
 301   float GetFlexBasis() const;
 302
 303   /**
 304    * @brief Set the shrink of the layout items.
 305    * @param[in] flexShrink The shrink of the items.
 306    */
 307   void SetFlexShrink(float flexShrink);
 308
 309   /**
 310    * @brief Get the shrink of the layout items.
 311    * @return The flex shrink.
 312    */
 313   float GetFlexShrink() const;
 314
 315   /**
 316    * @brief Set the grow of the layout items.
 317    * @param[in] flexGrow The grow of the items.
 318    */
 319   void SetFlexGrow(float flexGrow);
 320
 321   /**
 322    * @brief Get the grow of the layout items.
 323    * @return The flex grow.
 324    */
 325   float GetFlexGrow() const;
 326
 327   /**
 328    * @brief Set the margin.
 329    * @param[in] margin The margin value.
 330    */
 331   void SetMargin(Extents margin);
 332
 333   /**
 334    * @brief Set the padding.
 335    * @param[in] padding The padding value.
 336    */
 337   void SetPadding(Extents padding);
 338
 339 private:
 340   struct Impl;
 341   std::unique_ptr<Impl> mImpl;
 342
 343 }; // Node
 344
 345 } // namespace Flex
 346 } // namespace Toolkit
 347 } // namespace Dali
 348
 349 #endif // DALI_TOOLKIT_LAYOUTING_FLEX_NODE_H