1 #ifndef __DALI_TOOLKIT_FLEX_CONTAINER_H__
2 #define __DALI_TOOLKIT_FLEX_CONTAINER_H__
5 * Copyright (c) 2016 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 #include <dali-toolkit/public-api/controls/control.h>
30 namespace Internal DALI_INTERNAL
36 * @addtogroup dali_toolkit_controls_flex_container
41 * @brief FlexContainer implements a subset of the flexbox spec (defined by W3C):
43 * https://www.w3.org/TR/css3-flexbox/
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.
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
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".
58 * --------------------------------------------------------------- cross start
59 * | ------------------ --------|--------------------------- |
62 * | | flex item 1 | | | flex item 2 | | main axis
63 * |-|----------------|-|-------|--------------------------|-|------------>
67 * | ------------------ --------|--------------------------- |
68 * -----------------------------|--------------------------------- cross end
70 * | main start | cross axis | main end
76 * <h3>Per-child Custom properties for script supporting:</h3>
78 * The following custom properties of the actor are checked to decide how to lay out the
79 * actor inside the flex container.
81 * These properties are registered dynamically to the child and are non-animatable.
83 * | %Property Name | Type |
84 * |-------------------------|-------------|
86 * | alignSelf | integer |
87 * | flexMargin | Vector4 |
89 * The available values for alignSelf are: ALIGN_AUTO, ALIGN_FLEX_START, ALIGN_CENTER, ALIGN_FLEX_END, ALIGN_STRETCH
94 * "image":"image.png",
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.
104 class DALI_IMPORT_API FlexContainer : public Control
109 * @brief The direction of the main axis in the flex container. This determines
110 * the direction that flex items are laid out in the flex container.
115 COLUMN, ///< The flexible items are displayed vertically as a column @SINCE_1_1.35
116 COLUMN_REVERSE, ///< The flexible items are displayed vertically as a column, but in reverse order @SINCE_1_1.35
117 ROW, ///< The flexible items are displayed horizontally as a row @SINCE_1_1.35
118 ROW_REVERSE ///< The flexible items are displayed horizontally as a row, but in reverse order @SINCE_1_1.35
122 * @brief The primary direction in which content is ordered in the flex container
123 * and on which sides the “start” and “end” are.
126 enum ContentDirection
128 INHERIT, ///< Inherits the same direction from the parent @SINCE_1_1.35
129 LTR, ///< From left to right @SINCE_1_1.35
130 RTL ///< From right to left @SINCE_1_1.35
134 * @brief Alignment of the flex items when the items do not use all available
135 * space on the main-axis.
140 JUSTIFY_FLEX_START, ///< Items are positioned at the beginning of the container @SINCE_1_1.35
141 JUSTIFY_CENTER, ///< Items are positioned at the center of the container @SINCE_1_1.35
142 JUSTIFY_FLEX_END, ///< Items are positioned at the end of the container @SINCE_1_1.35
143 JUSTIFY_SPACE_BETWEEN, ///< Items are positioned with equal space between the lines @SINCE_1_1.35
144 JUSTIFY_SPACE_AROUND ///< Items are positioned with equal space before, between, and after the lines @SINCE_1_1.35
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.
154 ALIGN_AUTO, ///< Inherits the same alignment from the parent (only valid for "alignSelf" property) @SINCE_1_1.35
155 ALIGN_FLEX_START, ///< At the beginning of the container @SINCE_1_1.35
156 ALIGN_CENTER, ///< At the center of the container @SINCE_1_1.35
157 ALIGN_FLEX_END, ///< At the end of the container @SINCE_1_1.35
158 ALIGN_STRETCH ///< Stretch to fit the container @SINCE_1_1.35
162 * @brief The wrap type of the flex container when there is no enough room for
163 * all the items on one flex line.
168 NO_WRAP, ///< Flex items laid out in single line (shrunk to fit the flex container along the main axis) @SINCE_1_1.35
169 WRAP ///< Flex items laid out in multiple lines if needed @SINCE_1_1.35
175 * @brief The start and end property ranges for this control.
180 PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1, ///< @SINCE_1_1.35
181 PROPERTY_END_INDEX = PROPERTY_START_INDEX + 1000, ///< Reserve property indices @SINCE_1_1.35
183 CHILD_PROPERTY_START_INDEX = CHILD_PROPERTY_REGISTRATION_START_INDEX, ///< @SINCE_1_1.35
184 CHILD_PROPERTY_END_INDEX = CHILD_PROPERTY_REGISTRATION_START_INDEX + 1000 ///< Reserve child property indices @SINCE_1_1.35
188 * @brief An enumeration of properties belonging to the FlexContainer class.
195 // Event side properties
196 CONTENT_DIRECTION = PROPERTY_START_INDEX, ///< name "contentDirection", The primary direction in which content is ordered, @see FlexContainer::ContentDirection, type INTEGER @SINCE_1_1.35
197 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
198 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
199 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
200 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
201 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
206 * @brief An enumeration of child properties belonging to the FlexContainer class.
213 // Event side child properties
214 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
215 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 @SINCE_1_1.35
216 FLEX_MARGIN ///< name "flexMargin", The space around the flex item, type VECTOR4 @SINCE_1_1.35
221 * @brief Create a FlexContainer handle; this can be initialised with FlexContainer::New()
222 * Calling member functions with an uninitialised handle is not allowed.
228 * @brief Copy constructor. Creates another handle that points to the same real object
231 * @param[in] handle The handle to copy from
233 FlexContainer( const FlexContainer& handle );
236 * @brief Assignment operator. Changes this handle to point to another real object
238 * @param[in] handle Handle to an object
239 * @return A reference to this
241 FlexContainer& operator=( const FlexContainer& handle );
246 * @details This is non-virtual since derived Handle types must not contain data or virtual methods.
253 * @brief Create the FlexContainer control.
256 * @return A handle to the FlexContainer control.
258 static FlexContainer New();
261 * @brief Downcast an Object handle to FlexContainer.
263 * @details If handle points to a FlexContainer the downcast produces
264 * valid handle. If not the returned handle is left uninitialized.
268 * @param[in] handle Handle to an object
269 * @return handle to a FlexContainer or an uninitialized handle
271 static FlexContainer DownCast( BaseHandle handle );
274 public: // Not intended for application developers
278 * @brief Creates a handle using the Toolkit::Internal implementation.
281 * @param[in] implementation The Control implementation.
283 DALI_INTERNAL FlexContainer( Internal::FlexContainer& implementation );
286 * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
289 * @param[in] internal A pointer to the internal CustomActor.
291 explicit DALI_INTERNAL FlexContainer( Dali::Internal::CustomActor* internal );
298 } // namespace Toolkit
302 #endif // __DALI_TOOLKIT_FLEX_CONTAINER_H__