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