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