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