From 30ff20e521d003c00866bb3a821a5d36ca1d71f7 Mon Sep 17 00:00:00 2001
From: Agnelo Vaz <agnelo.vaz@samsung.com>
Date: Thu, 9 Nov 2017 11:50:43 +0000
Subject: [PATCH] Documenting ResourceReadySignal constraint/usage

Change-Id: I92cd68678a1f29d58f54c322ee7282b55c29f987
---
 dali-toolkit/public-api/controls/control.h         | 17 ++++++++++++++
 .../public-api/controls/image-view/image-view.h    | 26 ++++++++++++++++++++++
 2 files changed, 43 insertions(+)

diff --git a/dali-toolkit/public-api/controls/control.h b/dali-toolkit/public-api/controls/control.h
index 6d2f7e7..eee3b91 100644
--- a/dali-toolkit/public-api/controls/control.h
+++ b/dali-toolkit/public-api/controls/control.h
@@ -450,6 +450,23 @@ public:
    *
    * Most resources are only loaded when the control is placed on stage.
    *
+   * If resources are shared between ImageViews, they are cached.
+   * In this case, the ResourceReady signal may be sent before there is an object to connect to.
+   * To protect against this, IsResourceReady() can be checked first.
+   *
+   * @code
+   *    auto newControl = Control::New();
+   *    newControl.SetResource( resourceUrl );
+   *    if ( newControl.IsResourceReady() )
+   *    {
+   *       // do something
+   *    }
+   *    else
+   *    {
+   *      newControl.ResourceReadySignal.Connect( .... )
+   *    }
+   * @endcode
+   *
    * A callback of the following type may be connected:
    * @code
    *   void YourCallbackName( Control control );
diff --git a/dali-toolkit/public-api/controls/image-view/image-view.h b/dali-toolkit/public-api/controls/image-view/image-view.h
index 69bcbc3..b6f786b 100644
--- a/dali-toolkit/public-api/controls/image-view/image-view.h
+++ b/dali-toolkit/public-api/controls/image-view/image-view.h
@@ -44,6 +44,32 @@ class ImageView;
  *
  * An instance of ImageView can be created using a URL or an Image instance.
  *
+ * Some resources can be loaded before the ImageView is staged ( already cached ), in these cases if the connection to
+ * ResouceReadySignal is done after the resource is set then signal will be missed.
+ *
+ * To protect against this, IsResourceReady() can be checked before connecting to ResourceReadySignal,
+ * or the signal connection can be done before setting the resource"
+ *
+ * @code
+ *    auto myImageView = ImageView::New( resourceUrl );
+ *    if ( myImageView.IsResourceReady() )
+ *    {
+ *       // do something
+ *    }
+ *    else
+ *    {
+ *      myImageView.ResourceReadySignal.Connect( .... )
+ *    }
+ * @endcode
+ *
+ * OR Connect to signal before setting resource
+ *
+ * @code
+ *    auto myImageView = ImageView::New( resourceUrl );
+ *    myImageView.ResourceReadySignal.Connect( .... )
+ *    myImageView.SetProperty( ImageView::Property::IMAGE, resourceUrl );
+ * @endcode
+ *
  * @SINCE_1_0.0
  *
  */
-- 
2.7.4