dali-toolkit/devel-api/layouting/layout-item-impl.h

   1 #ifndef DALI_TOOLKIT_INTERNAL_LAYOUTING_LAYOUT_ITEM_H
   2 #define DALI_TOOLKIT_INTERNAL_LAYOUTING_LAYOUT_ITEM_H
   3 /*
   4  * Copyright (c) 2018 Samsung Electronics Co., Ltd.
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  * http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  */
  18
  19 #include <memory>
  20
  21 #include <dali/public-api/common/intrusive-ptr.h>
  22 #include <dali/public-api/object/base-object.h>
  23 #include <dali/public-api/object/property-map.h>
  24 #include <dali/public-api/object/type-registry.h>
  25 #include <dali/public-api/actors/actor-enumerations.h>
  26 #include <dali/public-api/animation/animation.h>
  27 #include <dali-toolkit/devel-api/layouting/child-layout-data.h>
  28 #include <dali-toolkit/devel-api/layouting/layout-item.h>
  29 #include <dali-toolkit/devel-api/layouting/layout-child-impl.h>
  30 #include <dali-toolkit/devel-api/layouting/layout-controller.h>
  31 #include <dali-toolkit/devel-api/layouting/layout-size.h>
  32 #include <dali-toolkit/devel-api/layouting/measure-spec.h>
  33 #include <dali-toolkit/devel-api/layouting/measured-size.h>
  34
  35 namespace Dali
  36 {
  37 namespace Toolkit
  38 {
  39 namespace Internal
  40 {
  41
  42 struct LayoutData;
  43
  44 class LayoutItem;
  45 using LayoutItemPtr = IntrusivePtr<LayoutItem>;
  46
  47 class LayoutTransitionData;
  48 using LayoutTransitionDataPtr = IntrusivePtr<LayoutTransitionData>;
  49
  50 /**
  51  * Base class for layouts.
  52  */
  53 class DALI_TOOLKIT_API LayoutItem : public BaseObject,
  54                                     public LayoutChild
  55 {
  56 public:
  57   /**
  58    * Constructor.
  59    */
  60   LayoutItem();
  61
  62 protected:
  63   /**
  64    * A reference counted object may only be deleted by calling Unreference()
  65    */
  66   virtual ~LayoutItem();
  67
  68 public:
  69
  70 /**
  71    * @brief Construct
  72    *
  73    * @param[in] owner The owner (container view / child view / visual ) of this layout
  74    * @return a new LayoutItem object
  75    */
  76   static LayoutItemPtr New( Handle& owner );
  77
  78   /**
  79    * @brief Remove the default copy constructor
  80    */
  81   LayoutItem(const LayoutItem& copy)=delete;
  82
  83   /**
  84    * @brief Remove the default assignment operator
  85    */
  86   LayoutItem& operator=(const LayoutItem& rhs)=delete;
  87
  88   /**
  89    * @brief Initialize the layout with it's owner and owner's type name
  90    * @param[in] owner a handle to the owner container
  91    * @param[in] containerType the type name of the owner container
  92    */
  93   void Initialize( Handle& owner, const std::string& containerType );
  94
  95   /**
  96    * @brief Get a handle to the owner of this layout
  97    *
  98    * @return a handle to the owner of this layout
  99    */
 100   Handle GetOwner() const;
 101
 102   /**
 103    * @brief Unparent this layout from it's parent, remove it from it's owner
 104    * and remove any layout children in derived types.
 105    */
 106   void Unparent();
 107
 108   /**
 109    * @brief Set whether this layout should be animated or not
 110    *
 111    * @param[in] animateLayout True if the layout should be animated when applied
 112    */
 113   void SetAnimateLayout( bool animateLayout );
 114
 115   /**
 116    * @brief Get whether this layout should be animated or not
 117    *
 118    * @return True if the layout should be animated when applied
 119    */
 120   bool IsLayoutAnimated() const;
 121
 122   /**
 123    * @brief Get the default transition
 124    *
 125    * @return The default transition
 126    */
 127   LayoutTransitionDataPtr GetDefaultTransition();
 128
 129   /**
 130    * @brief Set the layout transition data
 131    * @param[in] layoutTransitionType The type of the transition
 132    * @param[in] layoutTransitionDataPtr The transition data pointer
 133    */
 134   void SetTransitionData( int layoutTransitionType, LayoutTransitionDataPtr layoutTransitionDataPtr );
 135
 136   /**
 137    * @brief Get the transition data
 138    * @param[in] layoutTransitionType The type of the transition
 139    *
 140    * @return The transition
 141    */
 142   LayoutTransitionDataPtr GetTransitionData( int layoutTransitionType ) const;
 143
 144   /**
 145    * @brief  This is called to find out how big a layout should be.
 146    *
 147    * The parent supplies constraint information in the width and height parameters.
 148    *
 149    * The actual measurement work of a layout is performed in
 150    * {@link #OnMeasure(MeasureSpec, MeasureSpec)}, called by this method. Therefore, only
 151    * {@link #OnMeasure(MeasureSpec, MeasureSpec)} can and must be overridden by subclasses.
 152    *
 153    * @param[in] widthMeasureSpec Horizontal space requirements as imposed by the parent
 154    * @param[in] heightMeasureSpec Vertical space requirements as imposed by the parent
 155    *
 156    * @see #OnMeasure(MeasureSpec, MeasureSpec)
 157    */
 158   void Measure( MeasureSpec widthMeasureSpec, MeasureSpec heightMeasureSpec );
 159
 160   /**
 161    * @brief Assign a size and position to a layout and all of its descendants.
 162    *
 163    * This is the second phase of the layout mechanism.  (The first is measuring). In this phase, each parent
 164    * calls layout on all of its children to position them.  This is typically done using the child
 165    * measurements that were stored in the measure pass.
 166    *
 167    * Derived classes with children should override OnLayout. In that method, they should call Layout on each
 168    * of their children.
 169    *
 170    * @param[in] left position, relative to parent
 171    * @param[in] top position, relative to parent
 172    * @param[in] right position, relative to parent
 173    * @param[in] bottom position, relative to parent
 174    */
 175   void Layout( LayoutLength left, LayoutLength top, LayoutLength right, LayoutLength bottom );
 176
 177   /**
 178    * @brief Utility to return a default size.
 179    *
 180    * Uses the supplied size if the MeasureSpec imposed no constraints. Will get larger if allowed by the
 181    * MeasureSpec.
 182    *
 183    * @param[in] size Default size for this layout
 184    * @param[in] measureSpec Constraints imposed by the parent
 185    * @return The size this layout should be.
 186    */
 187   static LayoutLength GetDefaultSize( LayoutLength size, MeasureSpec measureSpec );
 188
 189   /**
 190    * @copydoc LayoutChild::SetParent
 191    */
 192   void SetParent( LayoutParent* parent ) override;
 193
 194   /**
 195    * @copydoc LayoutChild::GetParent
 196    */
 197   LayoutParent* GetParent() override;
 198
 199   /**
 200    * @brief Request that this layout is re-laid out.
 201    *
 202    * This will make this layout and all it's parent layouts dirty.
 203    */
 204   void RequestLayout();
 205
 206   /**
 207    * @brief Request that this layout is re-laid out with particular transition.
 208    * @param[in] layoutTranstionType The transition type
 209    *
 210    * This will make this layout and all it's parent layouts dirty and set the transition queued.
 211    */
 212   void RequestLayout( Dali::Toolkit::LayoutTransitionData::Type layoutTranstionType );
 213
 214   /**
 215    * @brief Request that this layout is re-laid out with particular transition.
 216    * @param[in] layoutTranstionType The transition type
 217    * @param[in] gainedChild The gained owners's child due to add/remove or focus gained/lost
 218    * @param[in] lostChild The lost owners's child due to add/remove or focus gained/lost
 219    *
 220    * This will make this layout and all it's parent layouts dirty and set the transition queued.
 221    */
 222   void RequestLayout( Dali::Toolkit::LayoutTransitionData::Type layoutTranstionType, Actor gainedChild, Actor lostChild );
 223
 224   /**
 225    * @brief Predicate to determine if this layout has been requested to re-layout
 226    *
 227    * @return True if a layout request has occured on this layout
 228    */
 229   bool IsLayoutRequested() const;
 230
 231   /**
 232    * @brief Set layout requested flag (mark the layout dirty).
 233    */
 234   void SetLayoutRequested();
 235
 236   /**
 237    * @brief Checks if the Resize policy is being used for this LayoutItem
 238    * @return true is ResizePolicy is used
 239    */
 240   bool IsResizePolicyRequired() const;
 241
 242   /**
 243    * @brief Sets if the ResizePolicy is needed or not for this LayoutItem
 244    * @param[in] resizeRequired true or false flag
 245    */
 246   void SetResizePolicyRequired( bool resizeRequired );
 247
 248   /**
 249    * @brief Get the measured width (without any measurement flags).
 250    *
 251    * This method should be used only during measurement and layout calculations.
 252    *
 253    * Use {@link Dali::Actor::GetTargetSize()} to see how wide a control is after layout
 254    */
 255   LayoutLength GetMeasuredWidth() const;
 256
 257   /**
 258    * @brief Get the measured height (without any measurement flags).
 259    *
 260    * This method should be used only during measurement and layout calculations.
 261    *
 262    * Use {@link Dali::Actor::GetTargetSize()} to see how high a control is after layout
 263    */
 264   LayoutLength GetMeasuredHeight() const;
 265
 266   /**
 267    * @brief Get the measured width and state.
 268    *
 269    * This method should be used only during measurement and layout calculations.
 270    *
 271    * Use {@link Dali::Actor::GetTargetSize()} to see how wide a view is after layout
 272    */
 273   MeasuredSize GetMeasuredWidthAndState() const;
 274
 275   /**
 276    * @brief Get the measured height and state.
 277    *
 278    * This method should be used only during measurement and layout calculations.
 279    *
 280    * Use {@link Dali::Actor::GetTargetSize()} to see how high a view is after layout
 281    */
 282   MeasuredSize GetMeasuredHeightAndState() const;
 283
 284   /**
 285    * @brief Returns the suggested minimum width that the layout should use.
 286    *
 287    * This returns the maximum of the layout's minimum width and the background's minimum width
 288    *
 289    * When being used in {@link #OnMeasure()}, the caller should still
 290    * ensure the returned width is within the requirements of the parent.
 291    *
 292    * @return The suggested minimum width of the layout.
 293    */
 294   LayoutLength GetSuggestedMinimumWidth() const;
 295
 296   /**
 297    * @brief Returns the suggested minimum height that the layout should use.
 298    *
 299    * This returns the maximum of the layout's minimum height and the background's minimum height
 300    *
 301    * When being used in {@link #OnMeasure()}, the caller should still
 302    * ensure the returned height is within the requirements of the parent.
 303    *
 304    * @return The suggested minimum height of the layout.
 305    */
 306   LayoutLength GetSuggestedMinimumHeight() const;
 307
 308   /**
 309    * @brief Sets the minimum width of the layout.
 310    *
 311    * It is not guaranteed the layout will be able to achieve this minimum width (for example, if its parent
 312    * layout constrains it with less available width).
 313    *
 314    * @param[in] minWidth The minimum width the layout will try to be, in pixels
 315    *
 316    * @see #GetMinimumWidth()
 317    */
 318   void SetMinimumWidth( LayoutLength minWidth );
 319
 320   /**
 321    * @brief Sets the minimum height of the layout.
 322    *
 323    * It is not guaranteed the layout will be able to achieve this minimum height (for example, if its parent
 324    * layout constrains it with less available height).
 325    *
 326    * @param[in] minHeight The minimum height the layout will try to be, in pixels
 327    *
 328    * @see #GetMinimumHeight()
 329    */
 330   void SetMinimumHeight( LayoutLength minHeight );
 331
 332   /**
 333    * @brief Returns the minimum width of the layout.
 334    *
 335    * @return the minimum width the layout will try to be, in pixels
 336    *
 337    * @see #SetMinimumWidth(LayoutLength)
 338    */
 339   LayoutLength GetMinimumWidth() const;
 340
 341   /**
 342    * @brief Returns the minimum height of the layout.
 343    *
 344    * @return the minimum height the layout will try to be, in pixels
 345    *
 346    * @see #SetMinimumHeight(LayoutLength)
 347    */
 348   LayoutLength GetMinimumHeight() const;
 349
 350   /**
 351    * Get the padding information.
 352    * @return The padding information
 353    */
 354   Extents GetPadding() const;
 355
 356   /**
 357    * Get the margin information.
 358    * @return The margin information
 359    */
 360   Extents GetMargin() const;
 361
 362   /**
 363    * @brief Sets the target width of the layout item.
 364    *
 365    * The item may not actually be drawn as this size but the value is stored
 366    * so if space allows it may take up this size at some point.
 367    *
 368    * @param[in] width The target width the layout will try to be, in pixels
 369    */
 370   void SetTargetWidth( LayoutLength width );
 371
 372   /**
 373    * @brief Sets the target height of the layout item.
 374    *
 375    * The item may not actually be drawn as this size but the value is stored
 376    * so if space allows it may take up this size at some point.
 377    *
 378    * @param[in] height The target width the layout will try to be, in pixels
 379    */
 380   void SetTargetHeight( LayoutLength height );
 381
 382   /**
 383    * @brief Gets the target width of this layout item.
 384    *
 385    * @return height The target width set on this layout item
 386    */
 387   LayoutLength GetTargetWidth() const;
 388
 389   /**
 390    * @brief Gets the target height of the layout item.
 391    *
 392    * @return height The target width set on this layout item
 393    */
 394   LayoutLength GetTargetHeight() const;
 395
 396 protected:
 397   /**
 398    * @brief Allow directly deriving classes to remove layout children when unparented
 399    */
 400   virtual void OnUnparent(){};
 401
 402   /**
 403    * @brief Ensure direct derived types register their child properties with the owner
 404    *
 405    * @param[in] containerType The type name of the owner container
 406    */
 407   virtual void OnRegisterChildProperties( const std::string& containerType );
 408
 409   /**
 410    * @brief Measure the layout and its content to determine the measured width and the
 411    * measured height.
 412    *
 413    * This method is invoked by {@link #Measure(MeasureSpec, MeasureSpec)} and
 414    * should be overridden by subclasses to provide accurate and efficient
 415    * measurement of their contents.
 416    *
 417    * <strong>CONTRACT:</strong> When overriding this method, you
 418    * <em>must</em> call {@link #SetMeasuredDimensions(MeasuredSize,MeasuredSize)} to store the
 419    * measured width and height of this layout. Failure to do so will trigger an
 420    * <code>IllegalStateException</code>, thrown by
 421    * {@link #Measure(MeasureSpec,MeasureSpec)}. Calling the superclass'
 422    * {@link #OnMeasure(MeasureSpec,MeasureSpec)} is a valid use.
 423    *
 424    * The base class implementation of measure defaults to the background size,
 425    * unless a larger size is allowed by the MeasureSpec. Subclasses should
 426    * override {@link #OnMeasure(MeasureSpec,MeasureSpec)} to provide better measurements of
 427    * their content.
 428    *
 429    * If this method is overridden, it is the subclass's responsibility to make
 430    * sure the measured height and width are at least the layout's minimum height
 431    * and width ({@link #GetSuggestedMinimumHeight()} and
 432    * {@link #GetSuggestedMinimumWidth()}).
 433    *
 434    * @param[in] widthMeasureSpec horizontal space requirements as imposed by the parent.
 435    *                             The requirements are encoded with
 436    *                             {@link MeasureSpec}.
 437    * @param[in] heightMeasureSpec vertical space requirements as imposed by the parent.
 438    *                              The requirements are encoded with
 439    *                              {@link MeasureSpec}.
 440    *
 441    * @see #GetMeasuredWidth()
 442    * @see #GetMeasuredHeight()
 443    * @see #GetSuggestedMinimumHeight()
 444    * @see #GetSuggestedMinimumWidth()
 445    * @see MeasureSpec#GetMode(int)
 446    * @see MeasureSpec#GetSize(int)
 447    */
 448   virtual void OnMeasure( MeasureSpec widthMeasureSpec, MeasureSpec heightMeasureSpec );
 449
 450   /**
 451    * @brief Called from Layout() when this layout should assign a size and position to each of its children.
 452    *
 453    * Derived classes with children should override this method and call Layout() on each of their children.
 454    *
 455    * @param[in] changed This is a new size or position for this layout
 456    * @param[in] left Left position, relative to parent
 457    * @param[in] top Top position, relative to parent
 458    * @param[in] right Right position, relative to parent
 459    * @param[in] bottom Bottom position, relative to parent
 460    */
 461   virtual void OnLayout( bool changed, LayoutLength left, LayoutLength top, LayoutLength right, LayoutLength bottom );
 462
 463
 464   /**
 465    * @brief This method must be called by {@link #OnMeasure(MeasureSpec,MeasureSpec)} to store the
 466    * measured width and measured height.
 467    *
 468    * Failing to do so will trigger an exception at measurement time.
 469    *
 470    * @param[in] measuredWidth The measured width of this layout. This may have a state of
 471    * {@link MeasuredSize::MEASURED_SIZE_TOO_SMALL}
 472    *
 473    * @param[in] measuredHeight The measured height of this layout. This may have a state of
 474    * {@link MeasuredSize::MEASURED_SIZE_TOO_SMALL}
 475    */
 476   void SetMeasuredDimensions( MeasuredSize measuredWidth, MeasuredSize measuredHeight );
 477
 478   /**
 479    * @brief Utility to reconcile a desired size and state, with constraints imposed by a MeasureSpec.
 480    *
 481    * @param[in] size How big the layout wants to be.
 482    * @param[in] measureSpec Constraints imposed by the parent.
 483    * @param[in] childMeasuredState Size information bit mask for the layout's children.
 484    *
 485    * @return A measured size, which may indicate that it is too small.
 486    */
 487   static MeasuredSize ResolveSizeAndState( LayoutLength size, MeasureSpec measureSpec,
 488                                            MeasuredSize::State childMeasuredState );
 489
 490   /**
 491    * @brief Sets the frame (the size and position) of the layout onto it's owner.
 492    * Collect all properties to animate after the layout update.
 493    *
 494    * @param[in] left The horizontal position of the left edge of this frame within the parent layout
 495    * @param[in] top The vertical position of the top edge of this frame within the parent layout
 496    * @param[in] right The horizontal position of the right edge of this frame within the parent layout
 497    * @param[in] bottom The vertical position of the bottom edge of this frame within the parent layout
 498    */
 499   bool SetFrame( LayoutLength left, LayoutLength top, LayoutLength right, LayoutLength bottom );
 500
 501   /**
 502    * Virtual method to inform derived classes when the layout size changed
 503    * @param[in] newSize The new size of the layout
 504    * @param[in] oldSize The old size of the layout
 505    */
 506   virtual void OnSizeChanged( LayoutSize newSize, LayoutSize oldSize );
 507
 508
 509   /**
 510    * @brief Initialization method for LayoutGroup to override
 511    */
 512   virtual void OnInitialize();
 513
 514   /**
 515    * @brief Called when a layer animation state is changed.
 516    */
 517   virtual void OnAnimationStateChanged( bool animateLayout ) {}
 518
 519 private:
 520   /**
 521    * @brief Called to change the size of the layout.
 522    *
 523    * @param[in] newSize The new size of the layout
 524    * @param[in] oldSize The old size of the layout
 525    */
 526   void SizeChange( LayoutSize newSize, LayoutSize oldSize );
 527
 528   /**
 529    * @brief Triggered when a layout animation finished.
 530    *
 531    * @param[in] animation  A handle to the layout animation
 532    */
 533   void OnLayoutAnimationFinished( Animation& animation );
 534
 535   /**
 536    * @brief Register child properties of layout with owner type.
 537    *
 538    * The Actor hierarchy uses these registered properties in the type
 539    * system to ensure child custom properties are properly initialized.
 540    *
 541    * @param[in] containerType The type of the containing view (owner)
 542    */
 543   void RegisterChildProperties( const std::string& containerType );
 544
 545 public:
 546   class Impl; // Class declaration is public so we can add devel API's in the future
 547
 548 private:
 549   std::unique_ptr<Impl> mImpl; ///< Implementation class holds all the data
 550   SlotDelegate<LayoutItem> mSlotDelegate;
 551 };
 552
 553 } //namespace Internal
 554
 555 inline Internal::LayoutItem& GetImplementation( Dali::Toolkit::LayoutItem& handle )
 556 {
 557   DALI_ASSERT_ALWAYS( handle && "LayoutItem handle is empty" );
 558   BaseObject& object = handle.GetBaseObject();
 559   return static_cast< Internal::LayoutItem& >( object );
 560 }
 561
 562 inline const Internal::LayoutItem& GetImplementation( const Dali::Toolkit::LayoutItem& handle )
 563 {
 564   DALI_ASSERT_ALWAYS( handle && "LayoutItem handle is empty" );
 565   const BaseObject& object = handle.GetBaseObject();
 566   return static_cast< const Internal::LayoutItem& >( object );
 567 }
 568
 569 } //namespace Toolkit
 570 } //namespace Dali
 571
 572 #endif // DALI_TOOLKIT_INTERNAL_LAYOUTING_LAYOUT_ITEM_H