Move Some Devel Properties & APIs to the Public API

[platform/core/uifw/dali-toolkit.git] / dali-toolkit / public-api / controls / control.h

diff --git a/dali-toolkit/public-api/controls/control.h b/dali-toolkit/public-api/controls/control.h
index c68d41a..8e522a2 100644 (file)
--- a/dali-toolkit/public-api/controls/control.h
+++ b/dali-toolkit/public-api/controls/control.h
@@ -28,6 +28,9 @@
 #include <dali/public-api/events/tap-gesture-detector.h>
 #include <dali/public-api/images/image.h>
 
+// INTERNAL INCLUDES
+#include <dali-toolkit/public-api/visuals/visual-properties.h>
+
 namespace Dali
 {
 
@@ -97,35 +100,65 @@ public:
     enum
     {
       /**
-       * @brief name "styleName", type std::string.
+       * @brief The name of the style to be applied to the control.
+       * @details Name "styleName", type Property::STRING.
+       * @see Toolkit::Control::SetStyleName()
        * @SINCE_1_0.0
-       * @see SetStyleName
        */
       STYLE_NAME = PROPERTY_START_INDEX,
+
       /**
        * @DEPRECATED_1_1.3
-       * @brief name "backgroundColor", mutually exclusive with BACKGROUND_IMAGE & BACKGROUND,  type Vector4.
+       * @brief The background color of the control.
+       *
+       * Mutually exclusive with BACKGROUND_IMAGE & BACKGROUND.
+       * @details Name "backgroundColor", type Property::VECTOR4.
+       * @see Toolkit::Control::SetStyleName()
        * @SINCE_1_0.0
-       * @see SetStyleName
        */
       BACKGROUND_COLOR,
+
       /**
        * @DEPRECATED_1_1.3
-       * @brief name "backgroundImage", mutually exclusive with BACKGROUND_COLOR & BACKGROUND,  type Map.
+       * @brief The background image of the control.
+       *
+       * Mutually exclusive with BACKGROUND_COLOR & BACKGROUND.
+       * @details Name "backgroundImage", type Property::MAP.
        * @SINCE_1_0.0
        */
       BACKGROUND_IMAGE,
+
       /**
-       * @brief name "keyInputFocus", type bool.
+       * @brief Receives key events to the control.
+       * @details Name "keyInputFocus", type Property::BOOLEAN.
+       * @see Toolkit::Control::SetKeyInputFocus()
        * @SINCE_1_0.0
-       * @see SetKeyInputFocus
        */
       KEY_INPUT_FOCUS,
+
       /**
-       * @brief name "background", mutually exclusive with BACKGROUND_COLOR & BACKGROUND_IMAGE, type Map or std::string for URL or Vector4 for Color.
+       * @brief The background of the control.
+       *
+       * Mutually exclusive with BACKGROUND_COLOR & BACKGROUND_IMAGE.
+       * @details Name "background", type Property::MAP or std::string for URL or Property::VECTOR4 for Color.
        * @SINCE_1_1.3
        */
       BACKGROUND,
+
+      /**
+       * @brief The outer space around the control.
+       * @details Name "margin", type Property::EXTENTS.
+       * @SINCE_1_2.62
+       * @note Margin property is to be supported by Layout algorithms and containers in future.
+       */
+      MARGIN,
+
+      /**
+       * @brief The inner space of the control.
+       * @details Name "padding", type Property::EXTENTS.
+       * @SINCE_1_2.62
+       */
+      PADDING
     };
   };
 
@@ -365,6 +398,15 @@ public:
    */
   bool IsResourceReady() const;
 
+  /**
+   * @brief Get the loading state of the visual resource.
+   *
+   * @SINCE_1_3_5
+   * @param[in] index The Property index of the visual
+   * @return Return the loading status (PREPARING, READY and FAILED) of visual resource
+   */
+  Visual::ResourceStatus GetVisualResourceStatus( const Dali::Property::Index index );
+
   // Signals
 
   /**
@@ -420,12 +462,30 @@ 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 );
    * @endcode
    *
    * @SINCE_1_2.60
+   * @return The signal to connect to
    * @note A RelayoutRequest is queued by Control before this signal is emitted
    */
   ResourceReadySignalType& ResourceReadySignal();