dali/public-api/object/property-notification.h

   1 #ifndef DALI_PROPERTY_NOTIFICATION_H
   2 #define DALI_PROPERTY_NOTIFICATION_H
   3
   4 /*
   5  * Copyright (c) 2020 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/public-api/object/base-handle.h>
  23 #include <dali/public-api/object/property-conditions.h>
  24 #include <dali/public-api/object/property-notification-declarations.h>
  25 #include <dali/public-api/object/property.h>
  26
  27 namespace Dali
  28 {
  29 /**
  30  * @addtogroup dali_core_object
  31  * @{
  32  */
  33
  34 namespace Internal DALI_INTERNAL
  35 {
  36 class PropertyNotification;
  37 }
  38
  39 /**
  40  * @brief This is used to issue a notification upon a condition of the property being met.
  41  *
  42  * For example checking if Actor::POSITION_X > 100.0.
  43  * @SINCE_1_0.0
  44  * @see Dali::PropertyCondition
  45  */
  46 class DALI_CORE_API PropertyNotification : public BaseHandle
  47 {
  48 public:
  49   /**
  50    * @brief Enumeration for description of how to check condition.
  51    * @SINCE_1_0.0
  52    */
  53   enum NotifyMode
  54   {
  55     DISABLED,         ///< Don't notify, regardless of result of Condition @SINCE_1_9.28
  56     NOTIFY_ON_TRUE,   ///< Notify whenever condition changes from false to true. @SINCE_1_9.28
  57     NOTIFY_ON_FALSE,  ///< Notify whenever condition changes from true to false. @SINCE_1_9.28
  58     NOTIFY_ON_CHANGED ///< Notify whenever condition changes (false to true, and true to false) @SINCE_1_9.28
  59   };
  60
  61 public:
  62   /**
  63    * @brief Creates an uninitialized PropertyNotification; this can be initialized with PropertyNotification::New().
  64    *
  65    * Calling member functions with an uninitialized Dali::Object is not allowed.
  66    * @SINCE_1_0.0
  67    */
  68   PropertyNotification();
  69
  70   /**
  71    * @brief Downcasts a handle to PropertyNotification handle.
  72    *
  73    * If handle points to a PropertyNotification object, the downcast
  74    * produces valid handle. If not, the returned handle is left
  75    * uninitialized.
  76    *
  77    * @SINCE_1_0.0
  78    * @param[in] handle to An object
  79    * @return handle to a PropertyNotification object or an uninitialized handle
  80    */
  81   static PropertyNotification DownCast(BaseHandle handle);
  82
  83   /**
  84    * @brief Destructor.
  85    *
  86    * This is non-virtual since derived Handle types must not contain data or virtual methods.
  87    * @SINCE_1_0.0
  88    */
  89   ~PropertyNotification();
  90
  91   /**
  92    * @brief This copy constructor is required for (smart) pointer semantics.
  93    *
  94    * @SINCE_1_0.0
  95    * @param[in] handle A reference to the copied handle
  96    */
  97   PropertyNotification(const PropertyNotification& handle);
  98
  99   /**
 100    * @brief This assignment operator is required for (smart) pointer semantics.
 101    *
 102    * @SINCE_1_0.0
 103    * @param[in] rhs A reference to the copied handle
 104    * @return A reference to this
 105    */
 106   PropertyNotification& operator=(const PropertyNotification& rhs);
 107
 108   /**
 109    * @brief Move constructor.
 110    *
 111    * @SINCE_1_9.22
 112    * @param[in] rhs A reference to the moved handle
 113    */
 114   PropertyNotification(PropertyNotification&& rhs) noexcept;
 115
 116   /**
 117    * @brief Move assignment operator.
 118    *
 119    * @SINCE_1_9.22
 120    * @param[in] rhs A reference to the moved handle
 121    * @return A reference to this handle
 122    */
 123   PropertyNotification& operator=(PropertyNotification&& rhs) noexcept;
 124
 125   /**
 126    * @brief Gets the condition of this notification.
 127    *
 128    * @SINCE_1_0.0
 129    * @return The condition is returned
 130    */
 131   PropertyCondition GetCondition();
 132
 133   /**
 134    * @brief Gets the condition of this notification.
 135    *
 136    * @SINCE_1_0.0
 137    * @return The condition is returned
 138    */
 139   const PropertyCondition& GetCondition() const;
 140
 141   /**
 142    * @brief Gets the target handle that this notification is observing.
 143    * @SINCE_1_0.0
 144    * @return The target handle
 145    */
 146   Dali::Handle GetTarget() const;
 147
 148   /**
 149    * @brief Gets the target handle's property index that this notification
 150    * is observing.
 151    *
 152    * @SINCE_1_0.0
 153    * @return The target property
 154    */
 155   Property::Index GetTargetProperty() const;
 156
 157   /**
 158    * @brief Sets the Notification mode.
 159    *
 160    * This determines how the property
 161    * notification should respond to the result of a condition.
 162    *
 163    * @SINCE_1_0.0
 164    * @param[in] mode Notification mode (Default is PropertyNotification::NOTIFY_ON_TRUE)
 165    */
 166   void SetNotifyMode(NotifyMode mode);
 167
 168   /**
 169    * @brief Retrieves the current Notification mode.
 170    *
 171    * @SINCE_1_0.0
 172    * @return Notification mode
 173    */
 174   NotifyMode GetNotifyMode();
 175
 176   /**
 177    * @brief Gets the result of the last condition check that caused a signal emit,
 178    * useful when using NOTIFY_ON_CHANGED mode and need to know what it changed to.
 179    *
 180    * @SINCE_1_0.0
 181    * @return whether condition result that triggered last emit was true or false
 182    */
 183   bool GetNotifyResult() const;
 184
 185   /**
 186    * @brief Connects to this signal to be notified when the notification has occurred.
 187    *
 188    * @SINCE_1_0.0
 189    * @return A signal object to Connect() with
 190    */
 191   PropertyNotifySignalType& NotifySignal();
 192
 193 public: // Not intended for use by Application developers
 194   /// @cond internal
 195   /**
 196    * @brief This constructor is used by Dali New() methods.
 197    *
 198    * @SINCE_1_0.0
 199    * @param[in] propertyNotification A pointer to a newly allocated Dali resource
 200    */
 201   explicit DALI_INTERNAL PropertyNotification(Internal::PropertyNotification* propertyNotification);
 202   /// @endcond
 203 };
 204
 205 /**
 206  * @}
 207  */
 208 } // namespace Dali
 209
 210 #endif // DALI_PROPERTY_NOTIFICATION_H