ZFPropertyDeclare.h File Reference

macros to declare ZFProperty More...

#include "ZFMethodDeclare.h"
#include "ZFObjectUtil.h"

Go to the source code of this file.

Macros
#define	ZFPropertyAccess(OwnerClass, Name)
	access the property directly, compile error if not declared
#define	ZFPropertyNoInitValue
	see ZFPROPERTY_RETAIN
#define	ZFPROPERTY_RETAIN(Type, Name, ...)
	declare a retain property
#define	ZFPROPERTY_RETAIN_READONLY(Type, Name, InitValueOrEmpty)
	see ZFPROPERTY_RETAIN
#define	ZFPROPERTY_RETAIN_DETAIL(Type, Name, InitValueOrEmpty, SetterAccessType, GetterAccessType)
	see ZFPROPERTY_RETAIN
#define	ZFPROPERTY_ASSIGN(Type, Name, ...)
	see ZFPROPERTY_RETAIN
#define	ZFPROPERTY_ASSIGN_READONLY(Type, Name, InitValueOrEmpty)
	see ZFPROPERTY_RETAIN
#define	ZFPROPERTY_ASSIGN_DETAIL(Type, Name, InitValueOrEmpty, SetterAccessType, GetterAccessType)
	see ZFPROPERTY_RETAIN
#define	ZFPROPERTY_ON_INIT_DECLARE(Type, Name)
	override life cycle callback for the property
#define	ZFPROPERTY_ON_INIT_DECLARE_NO_AUTO_INIT(Type, Name)
	see ZFPROPERTY_ON_INIT_DECLARE
#define	ZFPROPERTY_ON_INIT_DEFINE(OwnerClass, Type, Name)
	see ZFPROPERTY_ON_INIT_DECLARE
#define	ZFPROPERTY_ON_INIT_INLINE(Type, Name)
	see ZFPROPERTY_ON_INIT_DECLARE
#define	ZFPROPERTY_ON_INIT_INLINE_NO_AUTO_INIT(Type, Name)
	see ZFPROPERTY_ON_INIT_DECLARE
#define	ZFPROPERTY_ON_VERIFY_DECLARE(Type, Name)
	see ZFPROPERTY_ON_INIT_DECLARE
#define	ZFPROPERTY_ON_VERIFY_DEFINE(OwnerClass, Type, Name)
	see ZFPROPERTY_ON_INIT_DECLARE
#define	ZFPROPERTY_ON_VERIFY_INLINE(Type, Name)
	see ZFPROPERTY_ON_INIT_DECLARE
#define	ZFPROPERTY_ON_ATTACH_DECLARE(Type, Name)
	see ZFPROPERTY_ON_INIT_DECLARE
#define	ZFPROPERTY_ON_ATTACH_DEFINE(OwnerClass, Type, Name)
	see ZFPROPERTY_ON_INIT_DECLARE
#define	ZFPROPERTY_ON_ATTACH_INLINE(Type, Name)
	see ZFPROPERTY_ON_INIT_DECLARE
#define	ZFPROPERTY_ON_DETACH_DECLARE(Type, Name)
	see ZFPROPERTY_ON_INIT_DECLARE
#define	ZFPROPERTY_ON_DETACH_DEFINE(OwnerClass, Type, Name)
	see ZFPROPERTY_ON_INIT_DECLARE
#define	ZFPROPERTY_ON_DETACH_INLINE(Type, Name)
	see ZFPROPERTY_ON_INIT_DECLARE

Functions
const ZFProperty *	ZFPropertyForName (const zfchar *classNameOrFullName, const zfchar *propertyName)
	get property by name, or null if not registered

Detailed Description

macros to declare ZFProperty

Macro Definition Documentation

ZFPROPERTY_RETAIN

#define ZFPROPERTY_RETAIN	(		Type,
			Name,
			... )

declare a retain property

• ZFPROPERTY_XXX is similar to @property in Object-C, which would automatically generate setter and getter for you
  here's a list of what they'll generate (assume property's type is Type and property's name is yourPropName):
  • ZFPROPERTY_RETAIN:
    • public:
      virtual void yourPropName(Type const &propertyValue); // (reflectable)
      virtual Type const &yourPropName(void); // (reflectable)
  • ZFPROPERTY_ASSIGN:
    • public:
      virtual void yourPropName(Type const &propertyValue); // (reflectable)
      virtual Type const &yourPropName(void); // (reflectable)
  • for a retain property, Type must be ZFObject or ZFObject's subclass, and value is set by zfRetainChange, and would automatically be released when owner object deallocated
  • for a assign property, Type could be any type except for const type
  • when declare assign property as ZFObject type, it is automatically treated as weak property (similar to weak in Object-C)
• ZFProperty support those type only:
  • ZFObject *
  • all types that registered by ZFTYPEID_DECLARE
• ZFProperty is also reflectable, you may reflect the ZFProperty itself by ZFClass::propertyForName, or reflect the setter and getter as ZFMethod, for how to reflect, see ZFMethod, ZFOBJECT_REGISTER
  
• you may customize the accessibility for getter and setter, or add default value for setter, by using ZFPROPERTY_XXX_DETAIL:
  ZFPROPERTY_RETAIN_DETAIL( Type, Name, InitValueOrEmpty, SetterAccessType, GetterAccessType)
  the InitValueOrEmpty is the init value for the property, could be your_value or ZFPropertyNoInitValue, if not set, the built-in value would be set, e.g. zffalse for zfbool, empty string for zfstring (for retain property, the init value must be auto released object, use zfauto or zflineAlloc or zflineRelease is recommended)
  the SetterAccessType/GetterAccessType could be public/protected/private
  for example:

  zfclass OwnerClass : zfextend Base {
      ZFOBJECT_DECLARE(OwnerClass, Base)
   
      ZFPROPERTY_ASSIGN_DETAIL(
          zfstring, StringProperty, ZFPropertyNoInitValue,
          public, public)
  };

• to override a property in subclass, you may use ZFPROPERTY_ON_XXX

  Warning

  you must not declare two property with same name in child and base class

  Note

  overrided property won't be included in it's ZFClass, it's only a method override, no new ZFMethod or ZFProperty would be declared in child class

• to add Doxygen docs, you should:

  / **
    * @brief without fn defines, doc for getters only (ie. Name)
    *
    * setters' docs would be auto generated,
    * which is referencing to getters
    * /
   ZFPROPERTY_RETAIN(Type, Name)

ZFPROPERTY_ON_INIT_DECLARE

#define ZFPROPERTY_ON_INIT_DECLARE	(		Type,
			Name )

override life cycle callback for the property

proto type:

// for retain property
void propertyOnInit(
        ZF_IN_OUT zfauto [const] &propertyValue
        , ZF_IN zfauto const &propertyValueOld
        );
 
// for assign property
void propertyOnInit(
        ZF_IN_OUT YourPropertyType [const] &propertyValue
        , ZF_IN YourPropertyType const &propertyValueOld
        );

we have these property life cycle events:

• propertyOnInit: called when property first accessed
  you may change the propertyValue during this step to modify the property's init value
• propertyOnVerify: called when setter called
  you may verify the property value, and modify propertyValue to correct one
• propertyOnAttach: called when property first accessed or setter called
  you may do additional attach steps here, or apply your impl according to the property's new value
• propertyOnDetach: called when property setter called or owner object deallocated
  you may do additional detach steps here

after override, for detach events (detach/dealloc), subclass's one would be called before parent's one, for others (init/verify/attach), parent's one would be called first


here's a simple hint for the property's life cycle:

• property first time accessed:
  1. store raw init value
  2. propertyOnInit
  3. propertyOnAttach
• property's setter called:
  1. propertyOnDetach
  2. store raw value
  3. propertyOnVerify
  4. propertyOnAttach
  5. ZFObject::EventObjectPropertyValueOnUpdate
• property's owner object deallocated:
  1. propertyOnDetach

Note

if you override OnInit event from subclass of the property's owner class, the property's getter would be called during owner object's allocation to suit most logic case, which may cause unnecessary property allocation, to skip the step, use ZFPROPERTY_ON_INIT_DECLARE_NO_AUTO_INIT instead