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