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