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