Merge "Fix doxygen errors and enable doxygen build for devel-api" into devel/master
[platform/core/uifw/dali-toolkit.git] / 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  * | flexPadding             | Vector4     |
88  * | flexBorder              | Vector4     |
89  * | flexMargin              | Vector4     |
90  *
91  * The available values for alignSelf are: ALIGN_AUTO, ALIGN_FLEX_START, ALIGN_CENTER, ALIGN_FLEX_END, ALIGN_STRETCH
92  *
93  * @code
94  * "name":"icon",
95  * "type":"ImageView",
96  * "image":"image.png",
97  *   "customProperties": {
98  *     "flex":1,                        // property to make the item to receive the specified proportion of the free space in the container. If all items in the container use this pattern, their sizes will be proportional to the specified flex factor.
99  *     "alignSelf":"flexStart",         // property to specify how the item will align along the cross axis, if set, this overides the default alignment for all items in the container
100  *     "flexPadding":[10, 10, 10, 10],  // property to specify the space around the content (inside the flex border) of the item, if not set, default value is [0, 0, 0, 0]
101  *     "flexBorder":[5, 5, 5, 5],       // property to specify the border that goes around the flex padding and the content of the item, if not set, default value is [0, 0, 0, 0]
102  *     "flexMargin":[10, 10, 10, 10]    // property to specify the space outside the flex border, if not set, default value is [0, 0, 0, 0]
103  *   }
104  * @endcode
105  */
106
107 class DALI_IMPORT_API FlexContainer : public Control
108 {
109 public:
110
111   /**
112    * @brief The direction of the main axis in the flex container. This determines
113    * the direction that flex items are laid out in the flex container.
114    */
115   enum FlexDirection
116   {
117     COLUMN,                  ///< The flexible items are displayed vertically as a column
118     COLUMN_REVERSE,          ///< The flexible items are displayed vertically as a column, but in reverse order
119     ROW,                     ///< The flexible items are displayed horizontally as a row
120     ROW_REVERSE              ///< The flexible items are displayed horizontally as a row, but in reverse order
121   };
122
123   /**
124    * @brief The primary direction in which content is ordered in the flex container
125    * and on which sides the “start” and “end” are.
126    */
127   enum ContentDirection
128   {
129     INHERIT,                 ///< Inherits the same direction from the parent
130     LTR,                     ///< From left to right
131     RTL                      ///< From right to left
132   };
133
134   /**
135    * @brief Alignment of the flex items when the items do not use all available
136    * space on the main-axis.
137    */
138   enum Justification
139   {
140     JUSTIFY_FLEX_START,      ///< Items are positioned at the beginning of the container
141     JUSTIFY_CENTER,          ///< Items are positioned at the center of the container
142     JUSTIFY_FLEX_END,        ///< Items are positioned at the end of the container
143     JUSTIFY_SPACE_BETWEEN,   ///< Items are positioned with equal space between the lines
144     JUSTIFY_SPACE_AROUND     ///< Items are positioned with equal space before, between, and after the lines
145   };
146
147   /**
148    * @brief Alignment of the flex items or lines when the items or lines do not
149    * use all available space on the cross-axis.
150    */
151   enum Alignment
152   {
153     ALIGN_AUTO,              ///< Inherits the same alignment from the parent (only valid for "alignSelf" property)
154     ALIGN_FLEX_START,        ///< At the beginning of the container
155     ALIGN_CENTER,            ///< At the center of the container
156     ALIGN_FLEX_END,          ///< At the end of the container
157     ALIGN_STRETCH            ///< Stretch to fit the container
158   };
159
160   /**
161    * @brief The wrap type of the flex container when there is no enough room for
162    * all the items on one flex line.
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)
167     WRAP                     ///< Flex items laid out in multiple lines if needed
168   };
169
170 public:
171
172   /**
173    * @brief The start and end property ranges for this control.
174    */
175   enum PropertyRange
176   {
177     PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1,
178     PROPERTY_END_INDEX =   PROPERTY_START_INDEX + 1000              ///< Reserve property indices
179   };
180
181   /**
182    * @brief An enumeration of properties belonging to the FlexContainer class.
183    */
184   struct Property
185   {
186     enum
187     {
188       CONTENT_DIRECTION = PROPERTY_START_INDEX, ///< name "contentDirection",   The primary direction in which content is ordered,                                                 @see FlexContainer::ContentDirection,  type INTEGER
189       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
190       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
191       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
192       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
193       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
194     };
195   };
196
197   /**
198    * Create a FlexContainer handle; this can be initialised with FlexContainer::New()
199    * Calling member functions with an uninitialised handle is not allowed.
200    */
201   FlexContainer();
202
203   /**
204    * Copy constructor. Creates another handle that points to the same real object
205    * @param handle to copy from
206    */
207   FlexContainer( const FlexContainer& handle );
208
209   /**
210    * Assignment operator. Changes this handle to point to another real object
211    */
212   FlexContainer& operator=( const FlexContainer& handle );
213
214   /**
215    * @brief Destructor
216    *
217    * This is non-virtual since derived Handle types must not contain data or virtual methods.
218    */
219   ~FlexContainer();
220
221   /**
222    * Create the FlexContainer control.
223    * @return A handle to the FlexContainer control.
224    */
225   static FlexContainer New();
226
227   /**
228    * Downcast an Object handle to FlexContainer. If handle points to a FlexContainer the
229    * downcast produces valid handle. If not the returned handle is left uninitialized.
230    * @param[in] handle Handle to an object
231    * @return handle to a FlexContainer or an uninitialized handle
232    */
233   static FlexContainer DownCast( BaseHandle handle );
234
235
236 public: // Not intended for application developers
237
238   /**
239    * @brief Creates a handle using the Toolkit::Internal implementation.
240    *
241    * @param[in] implementation The Control implementation.
242    */
243   DALI_INTERNAL FlexContainer( Internal::FlexContainer& implementation );
244
245   /**
246    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
247    *
248    * @param[in] internal A pointer to the internal CustomActor.
249    */
250   explicit DALI_INTERNAL FlexContainer( Dali::Internal::CustomActor* internal );
251 };
252
253 /**
254  * @}
255  */
256 } // namespace Toolkit
257
258 } // namespace Dali
259
260 #endif // __DALI_TOOLKIT_FLEX_CONTAINER_H__