ZFStyleable.h File Reference

styleable More...

#include "ZFSerializable.h"
#include "ZFCopyable.h"
#include "ZFObjectObserver.h"

Go to the source code of this file.

Classes
class	ZFStyleable
	styleable element that can apply style from another object More...
class	ZFStyle
	common styleable object More...

Namespaces
namespace	ZFGlobalEvent

Macros
#define	ZFSTYLE_DEFAULT_DECLARE(YourStyle)
	used to declare a default style, see ZFStyleable
#define	ZFSTYLE_DEFAULT_DEFINE(YourStyle)
	see ZFSTYLE_DEFAULT_DECLARE
#define	ZFSTYLE_DEFAULT_AUTO_COPY()
	util macro to setup automatically copy style from ZFStyleable::defaultStyle
#define	ZFStyleUpdateBlock()
	util macro to call ZFStyleUpdateBegin/ZFStyleUpdateEnd
#define	ZFSTYLE_DECODER_DEFINE(registerSig, decodeAction, ...)
	register a custom decoder for ZFStyleSet

Functions
void	ZFStyleDefaultApplyAutoCopy (ZFStyleable *style)
	util method to setup automatically copy style from ZFStyleable::defaultStyle if its property value changed
void	ZFStyleSet (const zfstring &styleKey, ZFStyleable *styleValue)
	used to store style holder
zfauto	ZFStyleGet (const zfstring &styleKey)
	see ZFStyleSet
void	ZFStyleGetAll (ZFCoreArray< zfstring > &styleKey, ZFCoreArray< zfauto > &styleValue)
	get all styles, for debug use only, see ZFStyleSet
void	ZFStyleGetAllKeyT (ZFCoreArray< zfstring > &styleKey)
	see ZFStyleGetAll
ZFCoreArray< zfstring >	ZFStyleGetAllKey (void)
	see ZFStyleGetAll
void	ZFStyleGetAllValueT (ZFCoreArray< zfauto > &styleValue)
	see ZFStyleGetAll
ZFCoreArray< zfauto >	ZFStyleGetAllValue (void)
	see ZFStyleGetAll
void	ZFStyleRemoveAll (void)
	remove all styles, see ZFStyleSet
void	ZFStyleUpdateBegin ()
	see ZFStyleSet
void	ZFStyleUpdateEnd ()
	see ZFStyleSet
zfidentity	ZFGlobalEvent::E_ZFStyleOnUpdate (void)
	see ZFObject::observerNotify
zfidentity	ZFGlobalEvent::E_ZFStyleOnInvalid (void)
	see ZFObject::observerNotify

Detailed Description

styleable

Macro Definition Documentation

ZFSTYLE_DEFAULT_DECLARE

#define ZFSTYLE_DEFAULT_DECLARE

(

YourStyle

)

used to declare a default style, see ZFStyleable

usage:

// in h file
zfclass YourStyleableObject : zfextend ParentStyleable {
    ZFOBJECT_DECLARE(YourStyleableObject, ParentStyleable)
    ZFSTYLE_DEFAULT_DECLARE(YourStyleableObject)
};
 
// in cpp file
ZFSTYLE_DEFAULT_DEFINE(YourStyleableObject)

the macros above declare these types for you:

• default style access method: static zfanyT<YourObjectStyle> DefaultStyle(void); virtual zfanyT<ZFStyleable> defaultStyle(void);

Note

a style holder object would be created automatically when access the default style, and would be deleted automatically during ZFFrameworkCleanup with level ZFLevelZFFrameworkHigh, so it would result null if you access DefaultStyle before initialized or after it's deallocated

the default style holder object should only be used to hold the styles, typically you should not use it directly

it is useful to combine styleable logic and serializable logic, see ZFStyleSet for more info

for performance, the default style won't be copied to its instance by default, you may use ZFClass::instanceObserverAdd to observe styleable object's instance alloc event, and apply your default styles
or use ZFStyleDefaultApplyAutoCopy or ZFSTYLE_DEFAULT_AUTO_COPY to make the auto copy

ZFSTYLE_DEFAULT_AUTO_COPY

#define ZFSTYLE_DEFAULT_AUTO_COPY

(

)

util macro to setup automatically copy style from ZFStyleable::defaultStyle

use ZFINTERFACE_ON_INIT_DECLARE to copy styles during init, and use ZFStyleDefaultApplyAutoCopy to ensure default style value changes would be applied

ZFSTYLE_DECODER_DEFINE

#define ZFSTYLE_DECODER_DEFINE	(		registerSig,
			decodeAction,
			... )

register a custom decoder for ZFStyleSet

usage:

// in header file
/ **
 * add your doc here
 * /
#define ZFStyleDecoder_xxx xxx
 
ZFSTYLE_DECODER_DEFINE(ZFStyleDecoder_xxx, {
    // perform your decode action, proto type:
    //   zfbool decode(
    //           ZF_OUT zfauto &ret
    //           , ZF_IN const zfstring &styleKey
    //           );
})

all of the decoder would be executed once (order is not ensured) until success, if none returned true, builtin style map would be searched instead

Function Documentation

ZFStyleDefaultApplyAutoCopy()

void ZFStyleDefaultApplyAutoCopy ( ZFStyleable * style )

extern

util method to setup automatically copy style from ZFStyleable::defaultStyle if its property value changed

for performance, the default style won't be copied to each instance by default, by calling this method, when ZFStyleable::defaultStyle's property value changed, it would be copied to the registered instance

ZFStyleSet()

void ZFStyleSet ( const zfstring & styleKey, ZFStyleable * styleValue )

extern

used to store style holder

typical style logic are implemented by:

1. use ZFStyleable::styleKey to attach object to observe style change

1. use ZFStyleSet or ZFStyleLoad to modify styles

1. during style change event, all the styles would be copied automatically

example:

// register
MyStyleObject *obj = xxx;
obj->styleKey("MyStyle/MyStyleObject");
 
// change style
ZFStyleUpdateBegin();
    ZFStyleSet("MyStyle/MyStyleObject", xxx);
    ZFStyleUpdateBegin(); // can be embeded, but must be paired
        ZFStyleSet("xxx", xxx);
    ZFStyleUpdateEnd();
ZFStyleUpdateEnd();
 
// use ZFStyleLoad is recommended
ZFStyleLoad(xxx);

the style logic can also be used during serialization, when serializable contains key ZFSerializableKeyword_styleKey, the style would be copied during serialization, and restored when serialized back to data, a typical workflow:

// original src data
<MyStyleObject styleKey="MyStyle/MyStyleObject" overridedProp="overridedValue" />
 
// serialize from data
// step 1: load style and copy style to target object
<MyStyleObject someProp="styleValue" overridedProp="styleValue" />
// step 2: serialize as normal
<MyStyleObject someProp="styleValue" overridedProp="overridedValue" />
 
// serialize back to data
// step 1: serialize as normal
<MyStyleObject someProp="styleValue" overridedProp="overridedValue" />
// step 2: load referenced style object if exists
<ReferencedStyle someProp="styleValue" overridedProp="styleValue" />
// step 3: compare the target and referenced style object,
//         remove duplicate attributes
<MyStyleObject overridedProp="overridedValue" />
// step 4: finally restore the styleKey
<MyStyleObject styleKey="MyStyle/MyStyleObject" overridedProp="overridedValue" />
 
// note the final data is identical with original src data,
// and impl only needs to take care of refOwner
// during #ZFSerializable::serializeToData

by default, all ZFStyleable supports style logic, for non-ZFStyleable types, zfint for example, can also benifit from style logic if:

• registered by ZFTYPEID_DECLARE
• it's property declared by ZFPROPERTY_ASSIGN series

to apply style logic for these non-ZFStyleable types:

ownerZFStyleable->propStyle("yourPropertyName", "yourStyleKey");

when style of yourStyleKey changed, yourPropertyName's setter method would be called to apply the style


note, by default, all styles would be cleared during ZFFrameworkCleanup as level ZFLevelZFFrameworkNormal
ADVANCED:
you may register your own style decoder by ZFSTYLE_DECODER_DEFINE to supply additional style logic
by default, we bundled a special load logic by ZFStyleDecoder_ZFObjectIO, which would load style from specified path info, for example:

<MyStyleObject styleKey="@res!!my_cfg.xml" />

ZFStyleGet()

zfauto ZFStyleGet ( const zfstring & styleKey )

extern

see ZFStyleSet

Note

the returned object is the original object set by ZFStyleSet, use ZFStyleable::styleableCopyFrom or ZFCopyable::copy to create new one if necessary, you should not modify the original object