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 /**
  89  * Struct used for MeasureCallback
  90  */
  91 struct SizeTuple
  92 {
  93   SizeTuple( float x, float y ) : width( x ), height( y ){}
  94
  95   float width;
  96   float height;
  97 };
  98
  99 /**
 100  * @brief Callback signature for child Actor measure callback.
 101  * @note Actor, child Actor to measure
 102  * @note float, available width for child
 103  * @note int, width measure specifcation mode
 104  * @note float, available height for child
 105  * @note int, height measure specification mode
 106  */
 107 using MeasureCallback = SizeTuple (*)( Dali::Actor, float , int , float , int );
 108
 109 /**
 110  * This class provides the API for calling into the Flex layout implementation.
 111  */
 112 class DALI_TOOLKIT_API Node
 113 {
 114 public:
 115   /**
 116    * @brief Constructor.
 117    */
 118   Node();
 119
 120   /**
 121    * @brief Destructor.
 122    */
 123   ~Node();
 124
 125   Node& operator=(Node&&) = default;
 126   Node(Node&&) = default;
 127   Node(const Node&) = delete;
 128   Node& operator=(const Node&) = delete;
 129
 130   /**
 131    * @brief Insert child into the FlexLayout at the given index.
 132    * @param[in] child Actor to insert.
 133    * @param[in] margin of child Actor.
 134    * @param[in] measureFunction for the child.
 135    * @param[in] index to insert at.
 136    */
 137   void AddChild( Actor child, Extents margin, MeasureCallback measureFunction, int index );
 138
 139   /**
 140    * @brief Remove child from the FlexLayout at the given index.
 141    * @param[in] child child to be removed.
 142    */
 143   void RemoveChild( Actor child );
 144
 145   /**
 146    * @brief Return the dimensions of the node.
 147    * @param[in] width width specification
 148    * @param[in] widthMode width specification mode
 149    * @param[in] height height specification
 150    * @param[in] heightMode height specification mode
 151    * @return Size tuple representing the width and height of the node
 152    */
 153   SizeTuple MeasureNode( float width, int widthMode, float height, int heightMode );
 154
 155   /**
 156    * @brief Perform the layout measure calculations.
 157    * @param[in] availableWidth Amount of space available for layout, width.
 158    * @param[in] availableHeight Amount of space available for layout, height.
 159    * @param[in] isRTL Is the direction of the layout right to left.
 160    */
 161   void CalculateLayout( float availableWidth, float availableHeight, bool isRTL );
 162
 163   /**
 164    * @brief Get the calculated width of the given node.
 165    * @return the width of the node
 166    */
 167   float GetFlexWidth() const;
 168
 169   /**
 170    * @brief Get the calculated height of the given node.
 171    * @return the height of the node
 172    */
 173   float GetFlexHeight() const;
 174
 175   /**
 176    * @brief Get frame coordinates of the node at the given index.
 177    * @param[in] index of the child
 178    * @return Frame structure left x, top y, right z, bottom w
 179    */
 180   Vector4 GetNodeFrame(int index ) const;
 181
 182   /**
 183    * @brief Set the flex direction in the layout.
 184    * The direction of the main-axis which determines the direction that flex items are laid out.
 185    * @param[in] flexDirection The flex direction.
 186    */
 187   void SetFlexDirection( FlexDirection flexDirection );
 188
 189   /**
 190    * @brief Get the flex direction in the layout.
 191    * @return The flex direction.
 192    */
 193   FlexDirection GetFlexDirection() const;
 194
 195   /**
 196    * @brief Set the justification in the layout.
 197    * @param[in] flexJustification The flex justification.
 198    */
 199   void SetFlexJustification( Justification flexJustification );
 200
 201   /**
 202    * @brief Get the flex justification in the layout.
 203    * @return The flex justification.
 204    */
 205   Justification GetFlexJustification() const;
 206
 207   /**
 208    * @brief Set the wrap in the layout.
 209    * @param[in] flexWrap The flex wrap.
 210    */
 211   void SetFlexWrap(WrapType flexWrap );
 212
 213   /**
 214    * @brief Get the flex wrap in the layout.
 215    * @return The flex wrap.
 216    */
 217   WrapType GetFlexWrap() const;
 218
 219   /**
 220    * @brief Set the alignment of the layout content.
 221    * @param[in] flexAlignment The alignment of the content.
 222    */
 223   void SetFlexAlignment( Alignment flexAlignment );
 224
 225   /**
 226    * @brief Get the alignment of the layout content.
 227    * @return The flex content alignment.
 228    */
 229   Alignment GetFlexAlignment() const;
 230
 231   /**
 232    * @brief Set the alignment of the layout items.
 233    * @param[in] flexAlignment The alignment of the items.
 234    */
 235   void SetFlexItemsAlignment( Alignment flexAlignment );
 236
 237   /**
 238    * @brief Get the alignment of the layout items.
 239    * @return The flex items alignment.
 240    */
 241   Alignment GetFlexItemsAlignment() const;
 242
 243   /**
 244    * @brief Set the margin.
 245    * @param[in] margin The margin value.
 246    */
 247   void SetMargin( Extents margin );
 248
 249   /**
 250    * @brief Set the padding.
 251    * @param[in] padding The padding value.
 252    */
 253   void SetPadding( Extents padding );
 254
 255 private:
 256   struct Impl;
 257   std::unique_ptr< Impl > mImpl;
 258
 259 }; // Node
 260
 261
 262 } // namespace Flex
 263 } // namespace Toolkit
 264 } // namespace Dali
 265
 266 #endif // DALI_TOOLKIT_LAYOUTING_FLEX_NODE_H