dali-toolkit/public-api/controls/flex-container/flex-container.h

   1 #ifndef DALI_TOOLKIT_FLEX_CONTAINER_H
   2 #define DALI_TOOLKIT_FLEX_CONTAINER_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
  21 // INTERNAL INCLUDES
  22 #include <dali-toolkit/public-api/controls/control.h>
  23
  24 namespace Dali
  25 {
  26 namespace Toolkit
  27 {
  28 namespace Internal DALI_INTERNAL
  29 {
  30 class FlexContainer;
  31 }
  32
  33 /**
  34  * @addtogroup dali_toolkit_controls_flex_container
  35  * @{
  36  */
  37
  38 /**
  39  * @brief FlexContainer implements a subset of the flexbox spec (defined by W3C):
  40  *
  41  * https://www.w3.org/TR/css3-flexbox/
  42  *
  43  * It aims at providing a more efficient way to lay out, align and distribute space among
  44  * items in the container, even when their size is unknown or dynamic.
  45  *
  46  * FlexContainer has the ability to alter the width and height of its children (i.e. flex
  47  * items) to fill the available space in the best possible way on different screen sizes.
  48  * FlexContainer can expand items to fill available free space, or shrink them to prevent
  49  * overflow.
  50  *
  51  * Below is an illustration of the various directions and terms as applied to a flex
  52  * container with the "flex direction" defined as "row".
  53  *
  54  * @code
  55  *     flex container
  56  *    --------------------------------------------------------------- cross start
  57  *    | ------------------ --------|--------------------------- |
  58  *    | |                | |       |                          | |
  59  *    | |                | |       |                          | |
  60  *    | |  flex item 1   | |       |    flex item 2           | | main axis
  61  *    |-|----------------|-|-------|--------------------------|-|------------>
  62  *    | |                | |       |                          | |
  63  *    | |                | |       |                          | |
  64  *    | |                | |       |                          | |
  65  *    | ------------------ --------|--------------------------- |
  66  *    -----------------------------|--------------------------------- cross end
  67  *    |                            |                            |
  68  *    | main start                 | cross axis                 | main end
  69  *    |                            |                            |
  70  *                                 v
  71  * @endcode
  72  *
  73  * @nosubgrouping
  74  * <h3>Per-child Custom properties for script supporting:</h3>
  75  *
  76  * The following custom properties of the actor are checked to decide how to lay out the
  77  * actor inside the flex container.
  78  *
  79  * These properties are registered dynamically to the child and are non-animatable.
  80  *
  81  * | %Property Name          | Type        |
  82  * |-------------------------|-------------|
  83  * | flex                    | float       |
  84  * | alignSelf               | integer     |
  85  * | flexMargin              | Vector4     |
  86  *
  87  * The available values for alignSelf are: ALIGN_AUTO, ALIGN_FLEX_START, ALIGN_CENTER, ALIGN_FLEX_END, ALIGN_STRETCH
  88  *
  89  * @code
  90  * "name":"icon",
  91  * "type":"ImageView",
  92  * "image":"image.png",
  93  *   "properties": {
  94  *     "flex":1,                        // Property to make the item to receive the specified proportion of the free space in the container.
  95  *     "alignSelf":"flexStart",         // Property to specify how the item will align along the cross axis.
  96  *     "flexMargin":[10, 10, 10, 10]    // Property to specify the space around the item.
  97  *   }
  98  * @endcode
  99  * @SINCE_1_1.35
 100  */
 101
 102 class DALI_TOOLKIT_API FlexContainer : public Control
 103 {
 104 public:
 105   /**
 106    * @brief Enumeration for the direction of the main axis in the flex container. This determines
 107    * the direction that flex items are laid out in the flex container.
 108    * @SINCE_1_1.35
 109    */
 110   enum FlexDirection
 111   {
 112     COLUMN,         ///< The flexible items are displayed vertically as a column @SINCE_1_1.35
 113     COLUMN_REVERSE, ///< The flexible items are displayed vertically as a column, but in reverse order @SINCE_1_1.35
 114     ROW,            ///< The flexible items are displayed horizontally as a row @SINCE_1_1.35
 115     ROW_REVERSE     ///< The flexible items are displayed horizontally as a row, but in reverse order @SINCE_1_1.35
 116   };
 117
 118   /**
 119    * @brief Enumeration for the primary direction in which content is ordered in the flex container
 120    * and on which sides the “start” and “end” are.
 121    * @SINCE_1_1.35
 122    */
 123   enum ContentDirection
 124   {
 125     INHERIT, ///< Inherits the same direction from the parent @SINCE_1_1.35
 126     LTR,     ///< From left to right @SINCE_1_1.35
 127     RTL      ///< From right to left @SINCE_1_1.35
 128   };
 129
 130   /**
 131    * @brief Enumeration for the alignment of the flex items when the items do not use all available
 132    * space on the main-axis.
 133    * @SINCE_1_1.35
 134    */
 135   enum Justification
 136   {
 137     JUSTIFY_FLEX_START,    ///< Items are positioned at the beginning of the container @SINCE_1_1.35
 138     JUSTIFY_CENTER,        ///< Items are positioned at the center of the container @SINCE_1_1.35
 139     JUSTIFY_FLEX_END,      ///< Items are positioned at the end of the container @SINCE_1_1.35
 140     JUSTIFY_SPACE_BETWEEN, ///< Items are positioned with equal space between the lines @SINCE_1_1.35
 141     JUSTIFY_SPACE_AROUND,  ///< Items are positioned with equal space before, and after the lines @SINCE_1_1.35
 142     JUSTIFY_SPACE_EVENLY   ///< Items are positioned with equal space before, between, and after the lines @SINCE_2_0.29
 143   };
 144
 145   /**
 146    * @brief Enumeration for the alignment of the flex items or lines when the items or lines do not
 147    * use all the available space on the cross-axis.
 148    * @SINCE_1_1.35
 149    */
 150   enum Alignment
 151   {
 152     ALIGN_AUTO,       ///< Inherits the same alignment from the parent (only valid for "alignSelf" property) @SINCE_1_1.35
 153     ALIGN_FLEX_START, ///< At the beginning of the container @SINCE_1_1.35
 154     ALIGN_CENTER,     ///< At the center of the container @SINCE_1_1.35
 155     ALIGN_FLEX_END,   ///< At the end of the container @SINCE_1_1.35
 156     ALIGN_STRETCH     ///< Stretch to fit the container @SINCE_1_1.35
 157   };
 158
 159   /**
 160    * @brief Enumeration for the wrap type of the flex container when there is no enough room for
 161    * all the items on one flex line.
 162    * @SINCE_1_1.35
 163    */
 164   enum WrapType
 165   {
 166     NO_WRAP, ///< Flex items laid out in single line (shrunk to fit the flex container along the main axis) @SINCE_1_1.35
 167     WRAP     ///< Flex items laid out in multiple lines if needed @SINCE_1_1.35
 168   };
 169
 170 public:
 171   /**
 172    * @brief Enumeration for the start and end property ranges for this control.
 173    * @SINCE_1_1.35
 174    */
 175   enum PropertyRange
 176   {
 177     PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1, ///< @SINCE_1_1.35
 178     PROPERTY_END_INDEX   = PROPERTY_START_INDEX + 1000,             ///< Reserve property indices @SINCE_1_1.35
 179
 180     CHILD_PROPERTY_START_INDEX = CHILD_PROPERTY_REGISTRATION_START_INDEX,       ///< @SINCE_1_1.35
 181     CHILD_PROPERTY_END_INDEX   = CHILD_PROPERTY_REGISTRATION_START_INDEX + 1000 ///< Reserve child property indices @SINCE_1_1.35
 182   };
 183
 184   /**
 185    * @brief Enumeration for the instance of properties belonging to the FlexContainer class.
 186    * @SINCE_1_1.35
 187    */
 188   struct Property
 189   {
 190     /**
 191      * @brief Enumeration for the instance of properties belonging to the FlexContainer class.
 192      * @SINCE_1_1.35
 193      */
 194     enum
 195     {
 196       // Event side properties
 197       CONTENT_DIRECTION = PROPERTY_START_INDEX, ///< name "contentDirection",   The primary direction in which content is ordered,                                                 @see FlexContainer::ContentDirection,  type INTEGER @SINCE_1_1.35
 198       FLEX_DIRECTION,                           ///< name "flexDirection",      The direction of the main-axis which determines the direction that flex items are laid out,        @see FlexContainer::FlexDirection,     type INTEGER @SINCE_1_1.35
 199       FLEX_WRAP,                                ///< name "flexWrap",           Whether the flex items should wrap or not if there is no enough room for them on one flex line,    @see FlexContainer::WrapType,          type INTEGER @SINCE_1_1.35
 200       JUSTIFY_CONTENT,                          ///< name "justifyContent",     The alignment of flex items when the items do not use all available space on the main-axis,        @see FlexContainer::Justification,     type INTEGER @SINCE_1_1.35
 201       ALIGN_ITEMS,                              ///< name "alignItems",         The alignment of flex items when the items do not use all available space on the cross-axis,       @see FlexContainer::Alignment,         type INTEGER @SINCE_1_1.35
 202       ALIGN_CONTENT                             ///< name "alignContent",       Similar to "alignItems", but it aligns flex lines, so only works when there are multiple lines,    @see FlexContainer::Alignment,         type INTEGER @SINCE_1_1.35
 203     };
 204   };
 205
 206   /**
 207    * @brief Enumeration for the instance of child properties belonging to the FlexContainer class.
 208    * @SINCE_1_1.35
 209    */
 210   struct ChildProperty
 211   {
 212     /**
 213      * @brief Enumeration for the instance of child properties belonging to the FlexContainer class.
 214      * @SINCE_1_1.35
 215      */
 216     enum
 217     {
 218       // Event side child properties
 219       FLEX = CHILD_PROPERTY_START_INDEX, ///< name "flex",               The proportion of the free space in the container the flex item will receive. If all items in the container set this property, their sizes will be proportional to the specified flex factor,  type FLOAT @SINCE_1_1.35
 220       ALIGN_SELF,                        ///< name "alignSelf",          The alignment of the flex item along the cross axis, which, if set, overrides the default alignment for all items in the container,                         @see FlexContainer::Alignment,     type INTEGER @SINCE_1_1.35
 221       FLEX_MARGIN                        ///< name "flexMargin",         The space around the flex item,                                                                                                                                                                type VECTOR4 @SINCE_1_1.35
 222     };
 223   };
 224
 225   /**
 226    * @brief Creates a FlexContainer handle; this can be initialized with FlexContainer::New()
 227    * Calling member functions with an uninitialized handle is not allowed.
 228    * @SINCE_1_1.35
 229    */
 230   FlexContainer();
 231
 232   /**
 233    * @brief Copy constructor. Creates another handle that points to the same real object.
 234    * @SINCE_1_1.35
 235    *
 236    * @param[in] handle The handle to copy from
 237    */
 238   FlexContainer(const FlexContainer& handle);
 239
 240   /**
 241    * @brief Move constructor
 242    * @SINCE_1_9.23
 243    *
 244    * @param[in] rhs A reference to the moved handle
 245    */
 246   FlexContainer(FlexContainer&& rhs);
 247
 248   /**
 249    * @brief Assignment operator. Changes this handle to point to another real object.
 250    * @SINCE_1_1.35
 251    * @param[in] handle Handle to an object
 252    * @return A reference to this
 253    */
 254   FlexContainer& operator=(const FlexContainer& handle);
 255
 256   /**
 257    * @brief Move assignment
 258    * @SINCE_1_9.23
 259    *
 260    * @param[in] rhs A reference to the moved handle
 261    * @return A reference to this
 262    */
 263   FlexContainer& operator=(FlexContainer&& rhs);
 264
 265   /**
 266    * @brief Destructor.
 267    *
 268    * @details This is non-virtual since derived Handle types must not contain data or virtual methods.
 269    *
 270    * @SINCE_1_1.35
 271    */
 272   ~FlexContainer();
 273
 274   /**
 275    * @brief Creates the FlexContainer control.
 276    * @SINCE_1_1.35
 277    *
 278    * @return A handle to the FlexContainer control
 279    */
 280   static FlexContainer New();
 281
 282   /**
 283    * @brief Downcasts an Object handle to FlexContainer.
 284    *
 285    * @details If handle points to a FlexContainer, the downcast produces valid handle.
 286    * If not, the returned handle is left uninitialized.
 287    *
 288    * @SINCE_1_1.35
 289    *
 290    * @param[in] handle Handle to an object
 291    * @return Handle to a FlexContainer or an uninitialized handle
 292    */
 293   static FlexContainer DownCast(BaseHandle handle);
 294
 295 public: // Not intended for application developers
 296   /// @cond internal
 297   /**
 298    * @brief Creates a handle using the Toolkit::Internal implementation.
 299    * @SINCE_1_1.35
 300    *
 301    * @param[in] implementation The Control implementation
 302    */
 303   DALI_INTERNAL FlexContainer(Internal::FlexContainer& implementation);
 304
 305   /**
 306    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 307    * @SINCE_1_1.35
 308    *
 309    * @param[in] internal A pointer to the internal CustomActor
 310    */
 311   explicit DALI_INTERNAL FlexContainer(Dali::Internal::CustomActor* internal);
 312   /// @endcond
 313 };
 314
 315 /**
 316  * @}
 317  */
 318 } // namespace Toolkit
 319
 320 } // namespace Dali
 321
 322 #endif // DALI_TOOLKIT_FLEX_CONTAINER_H