dali-toolkit/public-api/controls/cluster/cluster.h

   1 #ifndef __DALI_TOOLKIT_CLUSTER_H__
   2 #define __DALI_TOOLKIT_CLUSTER_H__
   3
   4 /*
   5  * Copyright (c) 2014 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 // EXTERNAL INCLUDES
  22 #include <dali/public-api/animation/alpha-functions.h>
  23 #include <dali/public-api/animation/time-period.h>
  24
  25 // INTERNAL INCLUDES
  26 #include <dali-toolkit/public-api/controls/control.h>
  27
  28 namespace Dali
  29 {
  30
  31 namespace Toolkit
  32 {
  33
  34 namespace Internal DALI_INTERNAL
  35 {
  36 class Cluster;
  37 }
  38
  39 class ClusterStyle;
  40
  41 /**
  42  * @brief Cluster is a container of grouped actors positioned in different cluster styles.
  43  *
  44  * Actions
  45  * | %Action Name              | Method                    |
  46  * |---------------------------|---------------------------|
  47  * | expand                    | DoExpandAction()          |
  48  * | collapse                  | DoCollapseAction()        |
  49  * | transform                 | DoTransformAction()       |
  50  */
  51 class DALI_IMPORT_API Cluster : public Control
  52 {
  53 public:
  54
  55   // Custom properties
  56
  57   static const std::string CLUSTER_ACTOR_DEPTH;                           ///< Property, name "cluster-actor-depth",      type FLOAT
  58
  59 public:
  60
  61   /**
  62    * Create a Cluster handle; this can be initialised with Cluster::New()
  63    * Calling member functions with an uninitialised handle is not allowed.
  64    */
  65   Cluster();
  66
  67   /**
  68    * Copy Constructor.
  69    */
  70   Cluster( const Cluster& cluster );
  71
  72   /**
  73    * Assignment Operator.
  74    */
  75   Cluster& operator=( const Cluster& cluster );
  76
  77   /**
  78    * @brief Destructor
  79    *
  80    * This is non-virtual since derived Handle types must not contain data or virtual methods.
  81    */
  82   ~Cluster();
  83
  84   /**
  85    * Create the Cluster control with the given style.
  86    * @param[in] style The style of the cluster
  87    * @return A handle to the Cluster control.
  88    */
  89   static Cluster New( ClusterStyle& style );
  90
  91   /**
  92    * Downcast an Object handle to Cluster. If handle points to a Cluster the
  93    * downcast produces valid handle. If not the returned handle is left uninitialized.
  94    * @param[in] handle Handle to an object
  95    * @return handle to a Cluster or an uninitialized handle
  96    */
  97   static Cluster DownCast( BaseHandle handle );
  98
  99   /**
 100    * Adds a child to the Cluster
 101    * Will automatically choose a position for the child.
 102    * @pre The child actor has been initialized.
 103    * @param[in] child The child to add
 104    */
 105   void AddChild( Actor child );
 106
 107   /**
 108    * Adds a child to the Cluster
 109    * User specifies the position for the child.
 110    * @pre The child actor has been initialized.
 111    * @param[in] child The child to add
 112    * @param[in] positionIndex The position for this child
 113    */
 114   void AddChild( Actor child, unsigned int positionIndex );
 115
 116   /**
 117    * Adds a child to the Cluster to be inserted at a specified
 118    * depth index.
 119    * Will automatically choose a position for the child.
 120    * @pre The child actor has been initialized.
 121    * @param[in] child The child to add
 122    * @param[in] index The depth position for this child
 123    */
 124   void AddChildAt( Actor child, unsigned int index );
 125
 126   /**
 127    * Adds a child to the Cluster to be inserted at a specified
 128    * depth index.
 129    * User specifies the position for the child.
 130    * @pre The child actor has been initialized.
 131    * @param[in] child The child to add
 132    * @param[in] positionIndex The position for this child
 133    * @param[in] index The depth position for this child
 134    */
 135   void AddChildAt( Actor child, unsigned int positionIndex, unsigned int index );
 136
 137   /**
 138    * Returns a child from the given layout position
 139    * Note! if there is no child in this layout position this method returns an uninitialized
 140    * Actor handle
 141    * @param[in] index The child index in the cluster
 142    * @return The child that was in the layout position or an uninitialized handle
 143    */
 144   Actor GetChildAt( unsigned int index );
 145
 146   /**
 147    * Removes a child from the given layout position
 148    * Note! if there is no child in this layout position this method does nothing
 149    * @param[in] index The index of the child to remove
 150    * @return The child that was removed or an uninitialized handle
 151    */
 152   Actor RemoveChildAt( unsigned int index );
 153
 154   /**
 155    * Expands a child
 156    * A child will move away from the cluster.
 157    * @param[in] index The child position index to expand
 158    */
 159   void ExpandChild( unsigned int index );
 160
 161   /**
 162    * Expands all children
 163    * All children that have been collapsed will
 164    * move away from the cluster
 165    */
 166   void ExpandAllChildren();
 167
 168   /**
 169    * Collapses a child
 170    * A child that has been expanded will move
 171    * back to its original positions.
 172    * @param[in] index The child index to collapse
 173    * @param[in] front Whether to move child to the front or
 174    * back of cluster (depth).
 175    */
 176   void CollapseChild( unsigned int index, bool front = false );
 177
 178   /**
 179    * Collapses all children.
 180    * All children that have been expanded will move
 181    * back to their original positions.
 182    * @param[in] front Whether to move child to the front or
 183    * back of cluster (depth).
 184    */
 185   void CollapseAllChildren( bool front = false );
 186
 187   /**
 188    * Transforms Actor from default transform to new transform
 189    * @param[in] index The child index to move
 190    * @param[in] position The position to move to
 191    * @param[in] scale The scale to change to
 192    * @param[in] rotation The rotation to change to
 193    * @param[in] alpha The alpha function to use to tween to this transform
 194    * @param[in] period The duration for this transformation to take
 195    */
 196   void TransformChild( unsigned int index, const Vector3& position, const Vector3& scale, const Quaternion& rotation, AlphaFunction alpha, const TimePeriod& period );
 197
 198   /**
 199    * Restores Actor to the default transform (based on current style)
 200    * @param[in] index The child index to move back
 201    * @param[in] alpha The alpha function to use to tween to this transform
 202    * @param[in] period The duration for this transformation to take
 203    * @param[in] front Whether to move child to the front or
 204    * back of cluster (depth).
 205    */
 206   void RestoreChild( unsigned int index, AlphaFunction alpha, const TimePeriod& period, bool front = false );
 207
 208   /**
 209    * Sets the background image.
 210    * @param[in] image The background image.
 211    */
 212   void SetBackgroundImage( Actor image );
 213
 214   /**
 215    * Sets the title.
 216    *
 217    * @param[in] text Title text.
 218    */
 219   void SetTitle( Actor text );
 220
 221   /**
 222    * Sets the style of the cluster
 223    * @param[in] style The style of the cluster
 224    */
 225   void SetStyle(ClusterStyle style);
 226
 227   /**
 228    * Gets the style of the cluster
 229    * @return style of the cluster
 230    */
 231   ClusterStyle GetStyle() const;
 232
 233   /**
 234    * Gets the number of children that have been expanded in this cluster.
 235    * @return the number of children expanded.
 236    */
 237   unsigned int GetExpandedCount() const;
 238
 239   /**
 240    * Gets the number of children that have been added to this cluster.
 241    * @return the total number of children.
 242    */
 243   unsigned int GetTotalCount() const;
 244
 245 public: // Not intended for application developers
 246
 247   /**
 248    * Creates a handle using the Toolkit::Internal implementation.
 249    * @param[in]  implementation  The Control implementation.
 250    */
 251   DALI_INTERNAL Cluster( Internal::Cluster& implementation );
 252
 253   /**
 254    * Allows the creation of this Control from an Internal::CustomActor pointer.
 255    * @param[in]  internal  A pointer to the internal CustomActor.
 256    */
 257   explicit DALI_INTERNAL Cluster( Dali::Internal::CustomActor* internal );
 258 };
 259
 260 } // namespace Toolkit
 261
 262 } // namespace Dali
 263
 264 #endif // __DALI_TOOLKIT_CLUSTER_H__