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