class_property.h 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353
  1. // Copyright 2017 The Chromium Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license that can be
  3. // found in the LICENSE file.
  4. #ifndef UI_BASE_CLASS_PROPERTY_H_
  5. #define UI_BASE_CLASS_PROPERTY_H_
  6. #include <stdint.h>
  7. #include <map>
  8. #include <memory>
  9. #include <set>
  10. #include <type_traits>
  11. #include "base/component_export.h"
  12. #include "base/time/time.h"
  13. #include "ui/base/ui_base_types.h"
  14. // This header should be included by code that defines ClassProperties.
  15. //
  16. // To define a new ClassProperty:
  17. //
  18. // #include "foo/foo_export.h"
  19. // #include "ui/base/class_property.h"
  20. //
  21. // DEFINE_EXPORTED_UI_CLASS_PROPERTY_TYPE(FOO_EXPORT, MyType)
  22. // namespace foo {
  23. // // Use this to define an exported property that is primitive,
  24. // // or a pointer you don't want automatically deleted.
  25. // DEFINE_UI_CLASS_PROPERTY_KEY(MyType, kMyKey, MyDefault)
  26. //
  27. // // Use this to define an exported property whose value is a heap
  28. // // allocated object, and has to be owned and freed by the class.
  29. // DEFINE_OWNED_UI_CLASS_PROPERTY_KEY(gfx::Rect, kRestoreBoundsKey, nullptr)
  30. //
  31. // } // foo namespace
  32. //
  33. // To define a new type used for ClassProperty.
  34. //
  35. // // outside all namespaces:
  36. // DEFINE_EXPORTED_UI_CLASS_PROPERTY_TYPE(FOO_EXPORT, MyType)
  37. //
  38. // If a property type is not exported, use
  39. // DEFINE_UI_CLASS_PROPERTY_TYPE(MyType) which is a shorthand for
  40. // DEFINE_EXPORTED_UI_CLASS_PROPERTY_TYPE(, MyType).
  41. //
  42. // If the properties are used outside the file where they are defined
  43. // their accessor methods should also be declared in a suitable header
  44. // using DECLARE_EXPORTED_UI_CLASS_PROPERTY_TYPE(FOO_EXPORT, MyType)
  45. //
  46. // Cascading properties:
  47. //
  48. // Use the DEFINE_CASCADING_XXX macros to create a class property type that
  49. // will automatically search up an instance hierarchy for the first defined
  50. // property. This only affects the GetProperty() call. SetProperty() will
  51. // still explicitly set the value on the given instance. This is useful for
  52. // hierarchies of instances which a single set property can effect a whole sub-
  53. // tree of instances.
  54. //
  55. // In order to use this feature, you must override GetParentHandler() on the
  56. // class that inherits PropertyHandler.
  57. namespace ui {
  58. // Type of a function to delete a property that this window owns.
  59. using PropertyDeallocator = void(*)(int64_t value);
  60. template<typename T>
  61. struct ClassProperty {
  62. T default_value;
  63. const char* name;
  64. bool cascading = false;
  65. PropertyDeallocator deallocator;
  66. };
  67. namespace subtle {
  68. class PropertyHelper;
  69. }
  70. class COMPONENT_EXPORT(UI_BASE) PropertyHandler {
  71. public:
  72. PropertyHandler();
  73. PropertyHandler(PropertyHandler&& other);
  74. virtual ~PropertyHandler();
  75. PropertyHandler& operator=(PropertyHandler&& rhs) = default;
  76. // Takes the ownership of all the properties in |other|, overwriting any
  77. // similarly-keyed existing properties without affecting existing ones with
  78. // different keys.
  79. void AcquireAllPropertiesFrom(PropertyHandler&& other);
  80. // Sets the |value| of the given class |property|. Setting to the default
  81. // value (e.g., NULL) removes the property. The lifetime of objects set as
  82. // values of unowned properties is managed by the caller (owned properties are
  83. // freed when they are overwritten or cleared). NOTE: This should NOT be
  84. // for passing a raw pointer for owned properties. Prefer the std::unique_ptr
  85. // version below.
  86. template <typename T>
  87. void SetProperty(const ClassProperty<T>* property, T value);
  88. // Sets the |value| of the given class |property|, which must be an owned
  89. // property of pointer type. The property will be assigned a copy of |value|;
  90. // if no property object exists one will be allocated. T must support copy
  91. // construction and assignment.
  92. template <typename T>
  93. void SetProperty(const ClassProperty<T*>* property, const T& value);
  94. // Sets the |value| of the given class |property|, which must be an owned
  95. // property and of pointer type. The property will be move-assigned or move-
  96. // constructed from |value|; if no property object exists one will be
  97. // allocated. T must support at least copy (and ideally move) semantics.
  98. template <typename T>
  99. void SetProperty(const ClassProperty<T*>* property, T&& value);
  100. // Sets the |value| of the given class |property|, which must be an owned
  101. // property and of pointer type. Use std::make_unique<> or base::WrapUnique to
  102. // ensure proper ownership transfer.
  103. template <typename T>
  104. T* SetProperty(const ClassProperty<T*>* property, std::unique_ptr<T> value);
  105. // Returns the value of the given class |property|. Returns the
  106. // property-specific default value if the property was not previously set.
  107. // The return value is the raw pointer useful for accessing the value
  108. // contents.
  109. template<typename T>
  110. T GetProperty(const ClassProperty<T>* property) const;
  111. // Sets the |property| to its default value. Useful for avoiding a cast when
  112. // setting to NULL.
  113. template<typename T>
  114. void ClearProperty(const ClassProperty<T>* property);
  115. // Returns the value of all properties with a non-default value.
  116. std::set<const void*> GetAllPropertyKeys() const;
  117. protected:
  118. friend class subtle::PropertyHelper;
  119. virtual void AfterPropertyChange(const void* key, int64_t old_value) {}
  120. void ClearProperties();
  121. // Override this function when inheriting this class on a class or classes
  122. // in which instances are arranged in a parent-child relationship and
  123. // the intent is to use cascading properties.
  124. virtual PropertyHandler* GetParentHandler() const;
  125. // Called by the public {Set,Get,Clear}Property functions.
  126. int64_t SetPropertyInternal(const void* key,
  127. const char* name,
  128. PropertyDeallocator deallocator,
  129. int64_t value,
  130. int64_t default_value);
  131. // |search_parent| is required here for the setters to be able to look up the
  132. // current value of property only on the current instance without searching
  133. // the parent handler. This value is sent with the AfterPropertyChange()
  134. // notification.
  135. int64_t GetPropertyInternal(const void* key,
  136. int64_t default_value,
  137. bool search_parent) const;
  138. private:
  139. // Value struct to keep the name and deallocator for this property.
  140. // Key cannot be used for this purpose because it can be char* or
  141. // ClassProperty<>.
  142. struct Value {
  143. const char* name;
  144. int64_t value;
  145. PropertyDeallocator deallocator;
  146. };
  147. std::map<const void*, Value> prop_map_;
  148. };
  149. // No single new-style cast works for every conversion to/from int64_t, so we
  150. // need this helper class.
  151. template<typename T>
  152. class ClassPropertyCaster {
  153. public:
  154. static int64_t ToInt64(T x) { return static_cast<int64_t>(x); }
  155. static T FromInt64(int64_t x) { return static_cast<T>(x); }
  156. };
  157. template<typename T>
  158. class ClassPropertyCaster<T*> {
  159. public:
  160. static int64_t ToInt64(T* x) { return reinterpret_cast<int64_t>(x); }
  161. static T* FromInt64(int64_t x) { return reinterpret_cast<T*>(x); }
  162. };
  163. template <>
  164. class ClassPropertyCaster<base::TimeDelta> {
  165. public:
  166. static int64_t ToInt64(base::TimeDelta x) { return x.InMicroseconds(); }
  167. static base::TimeDelta FromInt64(int64_t x) { return base::Microseconds(x); }
  168. };
  169. namespace subtle {
  170. class COMPONENT_EXPORT(UI_BASE) PropertyHelper {
  171. public:
  172. template <typename T>
  173. static void Set(::ui::PropertyHandler* handler,
  174. const ::ui::ClassProperty<T>* property,
  175. T value) {
  176. int64_t old = handler->SetPropertyInternal(
  177. property, property->name,
  178. value == property->default_value ? nullptr : property->deallocator,
  179. ClassPropertyCaster<T>::ToInt64(value),
  180. ClassPropertyCaster<T>::ToInt64(property->default_value));
  181. if (property->deallocator &&
  182. old != ClassPropertyCaster<T>::ToInt64(property->default_value)) {
  183. (*property->deallocator)(old);
  184. }
  185. }
  186. template <typename T>
  187. static T Get(const ::ui::PropertyHandler* handler,
  188. const ::ui::ClassProperty<T>* property,
  189. bool allow_cascade) {
  190. return ClassPropertyCaster<T>::FromInt64(handler->GetPropertyInternal(
  191. property, ClassPropertyCaster<T>::ToInt64(property->default_value),
  192. property->cascading && allow_cascade));
  193. }
  194. template <typename T>
  195. static void Clear(::ui::PropertyHandler* handler,
  196. const ::ui::ClassProperty<T>* property) {
  197. Set(handler, property, property->default_value);
  198. }
  199. };
  200. } // namespace subtle
  201. // Template implementation is necessary in the .h file unless we want to break
  202. // [DECLARE|DEFINE]_EXPORTED_UI_CLASS_PROPERTY_TYPE() below into different
  203. // macros for owned and unowned properties; implementing them as pure templates
  204. // makes them nearly impossible to implement or use incorrectly at the cost of a
  205. // small amount of code duplication across libraries.
  206. template <typename T>
  207. void PropertyHandler::SetProperty(const ClassProperty<T*>* property,
  208. const T& value) {
  209. // Prevent additional heap allocation if possible.
  210. T* const old = subtle::PropertyHelper::Get<T*>(this, property, false);
  211. if (old) {
  212. T temp(*old);
  213. *old = value;
  214. AfterPropertyChange(property, reinterpret_cast<int64_t>(&temp));
  215. } else {
  216. SetProperty(property, std::make_unique<T>(value));
  217. }
  218. }
  219. template <typename T>
  220. void PropertyHandler::SetProperty(const ClassProperty<T*>* property,
  221. T&& value) {
  222. // Prevent additional heap allocation if possible.
  223. T* const old = subtle::PropertyHelper::Get<T*>(this, property, false);
  224. if (old) {
  225. T temp(std::move(*old));
  226. *old = std::forward<T>(value);
  227. AfterPropertyChange(property, reinterpret_cast<int64_t>(&temp));
  228. } else {
  229. SetProperty(property, std::make_unique<T>(std::forward<T>(value)));
  230. }
  231. }
  232. template <typename T>
  233. T* PropertyHandler::SetProperty(const ClassProperty<T*>* property,
  234. std::unique_ptr<T> value) {
  235. // This form only works for 'owned' properties.
  236. DCHECK(property->deallocator);
  237. T* value_ptr = value.get();
  238. subtle::PropertyHelper::Set<T*>(this, property, value.release());
  239. return value_ptr;
  240. }
  241. } // namespace ui
  242. // Macros to declare the property getter/setter template functions.
  243. #define DECLARE_EXPORTED_UI_CLASS_PROPERTY_TYPE(EXPORT, T) \
  244. namespace ui { \
  245. template <> \
  246. EXPORT void PropertyHandler::SetProperty(const ClassProperty<T>* property, \
  247. T value); \
  248. template <> \
  249. EXPORT T \
  250. PropertyHandler::GetProperty(const ClassProperty<T>* property) const; \
  251. template <> \
  252. EXPORT void PropertyHandler::ClearProperty( \
  253. const ClassProperty<T>* property); \
  254. } // namespace ui
  255. // Macros to instantiate the property getter/setter template functions.
  256. #define DEFINE_EXPORTED_UI_CLASS_PROPERTY_TYPE(EXPORT, T) \
  257. namespace ui { \
  258. template <> \
  259. EXPORT void PropertyHandler::SetProperty(const ClassProperty<T>* property, \
  260. T value) { \
  261. /* TODO(kylixrd, pbos): Once all the call-sites are fixed to only use */ \
  262. /* the unique_ptr version for owned properties, add the following */ \
  263. /* DCHECK to guard against passing raw pointers for owned properties. */ \
  264. /* DCHECK(!std::is_pointer<T>::value || */ \
  265. /* (std::is_pointer<T>::value && !property->deallocator)); */ \
  266. subtle::PropertyHelper::Set<T>(this, property, value); \
  267. } \
  268. template <> \
  269. EXPORT T \
  270. PropertyHandler::GetProperty(const ClassProperty<T>* property) const { \
  271. return subtle::PropertyHelper::Get<T>(this, property, true); \
  272. } \
  273. template <> \
  274. EXPORT void PropertyHandler::ClearProperty( \
  275. const ClassProperty<T>* property) { \
  276. subtle::PropertyHelper::Clear<T>(this, property); \
  277. } \
  278. } // namespace ui
  279. #define DEFINE_UI_CLASS_PROPERTY_TYPE(T) \
  280. DEFINE_EXPORTED_UI_CLASS_PROPERTY_TYPE(, T)
  281. #define DEFINE_UI_CLASS_PROPERTY_KEY(TYPE, NAME, DEFAULT) \
  282. static_assert(sizeof(TYPE) <= sizeof(int64_t), "property type too large"); \
  283. const ::ui::ClassProperty<TYPE> NAME##_Value = {DEFAULT, #NAME, false, \
  284. nullptr}; \
  285. const ::ui::ClassProperty<TYPE>* const NAME = &NAME##_Value;
  286. #define DEFINE_OWNED_UI_CLASS_PROPERTY_KEY(TYPE, NAME, DEFAULT) \
  287. namespace { \
  288. void Deallocator##NAME(int64_t p) { \
  289. enum { type_must_be_complete = sizeof(TYPE) }; \
  290. delete ::ui::ClassPropertyCaster<TYPE*>::FromInt64(p); \
  291. } \
  292. const ::ui::ClassProperty<TYPE*> NAME##_Value = {DEFAULT, #NAME, false, \
  293. &Deallocator##NAME}; \
  294. } /* namespace */ \
  295. const ::ui::ClassProperty<TYPE*>* const NAME = &NAME##_Value;
  296. #define DEFINE_CASCADING_UI_CLASS_PROPERTY_KEY(TYPE, NAME, DEFAULT) \
  297. static_assert(sizeof(TYPE) <= sizeof(int64_t), "property type too large"); \
  298. const ::ui::ClassProperty<TYPE> NAME##_Value = {DEFAULT, #NAME, true, \
  299. nullptr}; \
  300. const ::ui::ClassProperty<TYPE>* const NAME = &NAME##_Value;
  301. #define DEFINE_CASCADING_OWNED_UI_CLASS_PROPERTY_KEY(TYPE, NAME, DEFAULT) \
  302. namespace { \
  303. void Deallocator##NAME(int64_t p) { \
  304. enum { type_must_be_complete = sizeof(TYPE) }; \
  305. delete ::ui::ClassPropertyCaster<TYPE*>::FromInt64(p); \
  306. } \
  307. const ::ui::ClassProperty<TYPE*> NAME##_Value = {DEFAULT, #NAME, true, \
  308. &Deallocator##NAME}; \
  309. } /* namespace */ \
  310. const ::ui::ClassProperty<TYPE*>* const NAME = &NAME##_Value;
  311. #endif // UI_BASE_CLASS_PROPERTY_H_