SFYDistributer

Class which distributes an event to a responder tree.

#include <SFYDistributer.h.hpp>

class SFYDistributer;

SFMTYPEDEFCLASS(SFYDistributer)

Collaboration diagram

Description

This class distributes an event to the responder tree. Some private functions of this class are used only in the SFYResponder class and will not be used directly in the applet development.

Since the SFYApplication class contains an instance of this class by default and automatically performs all the calling and setting necessary for the application, you don't have to operate on this class.

In case of contructing another responder tree, developer needs to use this class directly as the code below. At this time, in order to distribute an event to the responder tree, the instance of this class needs to be bound with the root responder of the responder tree.

Example 866. Construct the responder tree

SFYDistributer _distributer;
SFZRootSmp _root;
SFCError error;

// initialize the SFYDistributer instance 
if ((error = _distributer.Initialize()) == SFERR_NO_ERROR) {

    // create the root of the responder tree
    if ((_root = SFZRoot::NewInstance(&error)) != null) {

        // bind the root of the responder tree with the SFYDistributer instance
        _root->SetDistributer(&_distributer);

        // here describe other initialization
        _root->SetRealBound(_root->GetSuitableBound());
        _root->SetStateVisible(true);
        ...
    }
}

Example 867. Release the responder tree

SFYDistributer _distributer;
SFZRootSmp _root;

...

// release the SFYDistributer instance after the responder tree
_root.Release();
_distributer.Terminate();

Example 868. Distribute an event to the responder tree

SFZRootSmp _root;
SFXEvent event;
SFCError error;

...

// to distribute an event to the responder tree, call the distribute function of root responder
error = _root->Distribute(event);

Reference

Member

Constructor/Destructor
SFYDistributer( `Void` ) Constructor of the SFYDistributer class.
~SFYDistributer( `Void` ) Destructor of the SFYDistributer class.

Public Functions
`Void`	ClearHandler( `Void` ) Unregister all handlers from this SFYDistributer instance.
`Void`	ClearTracer( `Void` ) Unregister all dispatching rules from the tracer of this SFYDistributer instance.
`SFCError`	Initialize( `Void` ) Initialize this distributer.
`SFCError`	RegisterHandler( `SFXEventRangeConstRef` range , `SFYHandler::RuleRecConstRef` rule ) Register the handler.
`SFCError`	RegisterHandler( `SFXEventRangeConstRef` range , `SFYHandler::HandlerSPP` spp , `VoidPtr` reference ) Register the handler.
`SFCError`	RegisterHandler( `SFXEventRangeConstPtr` range , `SFYHandler::RuleRecConstPtr` rule , `SInt32` length ) Register the handler.
`SFCError`	RegisterHandler( `SFXEventRangeConstPtr` range , `SFYHandler::HandlerSPPConstPtr` spp , `VoidPtrConstPtr` reference , `SInt32` length ) Register the handler.
`SFCError`	RegisterTracer( `SFXEventRangeConstRef` range , `SFYTracer::RuleRecConstRef` rule ) Register the tracer.
`SFCError`	RegisterTracer( `SFXEventRangeConstRef` range , `SFYTracer::OrderEnum` order , `SFYTracer::StateEnum` state , `Bool` overload ) Register the tracer.
`SFCError`	RegisterTracer( `SFXEventRangeConstPtr` range , `SFYTracer::RuleRecConstPtr` rule , `SInt32` length ) Register the tracer.
`SFCError`	RegisterTracer( `SFXEventRangeConstPtr` range , `SFYTracer::OrderEnumConstPtr` order , `SFYTracer::StateEnumConstPtr` state , `BoolConstPtr` overload , `SInt32` length ) Register the tracer.
`Void`	Terminate( `Void` ) Terminate this distributer.
`Void`	UnregisterHandler( `SFXEventRangeConstRef` range , `SFYHandler::RuleRecConstRef` rule ) Unregister the handles from this distributer that match the specified condition.
`Void`	UnregisterHandler( `SFXEventRangeConstRef` range , `SFYHandler::HandlerSPP` spp , `VoidPtr` reference ) Unregister the handles from this distributer that match the specified condition.
`Void`	UnregisterHandler( `SFXEventRangeConstPtr` range , `SFYHandler::RuleRecConstPtr` rule , `SInt32` length ) Unregister the handles from this distributer that match the specified condition.
`Void`	UnregisterHandler( `SFXEventRangeConstPtr` range , `SFYHandler::HandlerSPPConstPtr` spp , `VoidPtrConstPtr` reference , `SInt32` length ) Unregister the handles from this distributer that match the specified condition.
`Void`	UnregisterTracer( `SFXEventRangeConstRef` range ) Unregister the dispatching rules from the tracer of this distributer which matches the specified condition.
`Void`	UnregisterTracer( `SFXEventRangeConstPtr` range , `SInt32` length ) Unregister the dispatching rules from the tracer of this distributer which matches the specified condition.

SFYDistributer::SFYDistributer

Constructor of the SFYDistributer class.

[ public, explicit ]
SFYDistributer(Void);

SFYDistributer::~SFYDistributer

Destructor of the SFYDistributer class.

[ public ]
~SFYDistributer(Void);

SFYDistributer::ClearHandler

Unregister all handlers from this SFYDistributer instance.

[ public ]
Void ClearHandler(Void);

Description

This function unregisters all handlers from this SFYDistributer instance.

Reference

SFYDistributer::RegisterHandler | SFYDistributer::UnregisterHandler | SFYDistributer | Handler

SFYDistributer::ClearTracer

Unregister all dispatching rules from the tracer of this SFYDistributer instance.

[ public ]
Void ClearTracer(Void);

Description

This function unregisters all dispatching rules from the tracer of this SFYDistributer instance.

Reference

SFYDistributer::RegisterTracer | SFYDistributer::UnregisterTracer | SFYDistributer | Tracer

SFYDistributer::Initialize

Initialize this distributer.

[ public ]
SFCError Initialize(Void);

Return value

If succeeds: SFERR_NO_ERROR
If insufficient memory: SFERR_NO_MEMORY

Description

This function initializes all the resources necessary for distributing an event to the responders of the responder tree bound with this distributer.

Before binding this distributer with the responder tree, it needs to be initialized by calling this function.

Reference

SFYDistributer::RegisterHandler

[ public ]
SFCError RegisterHandler(
    SFXEventRangeConstRef range        // event range
    SFYHandler::RuleRecConstRef rule   // handler rule
);

[ public ]
SFCError RegisterHandler(
    SFXEventRangeConstRef range   // event range
    SFYHandler::HandlerSPP spp    // handler function
    VoidPtr reference             // reference value
);

[ public ]
SFCError RegisterHandler(
    SFXEventRangeConstPtr range        // array of event range
    SFYHandler::RuleRecConstPtr rule   // array of handler rule
    SInt32 length                      // number of the elements of the array
);

[ public ]
SFCError RegisterHandler(
    SFXEventRangeConstPtr range          // array of event range
    SFYHandler::HandlerSPPConstPtr spp   // array of handler function
    VoidPtrConstPtr reference            // array of reference value
    SInt32 length                        // number of the elements of the array
);

Argument

range: represents the range of events which the handler will receive.
rule: represents the set of handler functions and reference values.

Return value

If succeeds: SFERR_NO_ERROR
If invalid parameter: SFERR_INVALID_PARAM
If insufficient memory: SFERR_NO_MEMORY

Description

This function registers specified handlers into this SFYDistributer instance.

It is possible to register more than one handler for the same event. At this time, handlers are called in the registered order or vice versa. If an event is handled by a handler, whether or not to boot up the next handler as long as it exists depends on the settings.

Method to receive the BREW-defined event whose dispatching rule is registered into the standard tracer with "distributing condition: None[SFYTracer::STATE_NONE]"

	Method to receive the BREW-defined event whose dispatching rule is registered into the standard tracer with "distributing condition: None[SFYTracer::STATE_NONE]"
The BREW-defined event whose dispatching rule is registered into the standard tracer with "distributing condition: None[SFYTracer::STATE_NONE] will be distributed to no responder including the root(`SFZRoot`) which the `SFYApplication` class contains by default. This is because the rules of the standard tracer are registered into the `SFYDistributer` instance. To receive this event, you have to register its handler directly into the `SFYDistributer` instance as follows: Get the `SFYDistributer` instance using the `SFYApplication::GetDistributer` function. Register the handler for this event using the `SFYDistributer::RegisterHandler` function. Though this handler may be defined anywhere, not pointer to a responder but "null" will be passed via the "invoker" parameter. Note this matter in case the invoker parameter will be used.

The BREW-defined event whose dispatching rule is registered into the standard tracer with "distributing condition: None[SFYTracer::STATE_NONE] will be distributed to no responder including the root(SFZRoot) which the SFYApplication class contains by default.

This is because the rules of the standard tracer are registered into the SFYDistributer instance.

To receive this event, you have to register its handler directly into the SFYDistributer instance as follows:

Get the SFYDistributer instance using the SFYApplication::GetDistributer function.
Register the handler for this event using the SFYDistributer::RegisterHandler function.
Though this handler may be defined anywhere, not pointer to a responder but "null" will be passed via the "invoker" parameter. Note this matter in case the invoker parameter will be used.

Example

SFYDistributer _distributer;
SFCError error;

register one handler at a time
error = _distributer.RegisterHandler(SFXEventRange(SFEVT_KEY, SFEVT_KEY, SFP16_BEGIN, SFP16_END), 
                        XANDLER_INTERNAL(OnKey)
        );


register more than one handler at a time together
static SFXEventRange::AtomRecConst range[] = {
    {      SFEVT_KEY,       SFEVT_KEY,   SFP16_BEGIN,     SFP16_END},
    {SFEVT_KEY_PRESS, SFEVT_KEY_PRESS,   SFP16_BEGIN,     SFP16_END},
    {     SFEVT_KEY_RELEASE,      SFEVT_KEY_RELEASE,   SFP16_BEGIN,     SFP16_END}
};
SFYHandler::RuleRec rule[lengthof(range)];

rule[0].spp = XANDLER_FUNCTION(OnKey);
rule[0].reference = this;
rule[1].spp = XANDLER_FUNCTION(OnKeyPress);
rule[1].reference = this;
rule[2].spp = XANDLER_FUNCTION(OnKeyRelease);
rule[2].reference = this;

error = _distributer.RegisterHandler(atomic_cast(range), rule, lengthof(range));

Reference

SFYDistributer::RegisterTracer

[ public ]
SFCError RegisterTracer(
    SFXEventRangeConstRef range       // event range
    SFYTracer::RuleRecConstRef rule   // tracer rule
);

[ public ]
SFCError RegisterTracer(
    SFXEventRangeConstRef range   // event range
    SFYTracer::OrderEnum order    // processing order
    SFYTracer::StateEnum state    // distributing condition
    Bool overload                 // overloading condition
);

[ public ]
SFCError RegisterTracer(
    SFXEventRangeConstPtr range       // array of event range
    SFYTracer::RuleRecConstPtr rule   // array of tracer rule
    SInt32 length                     // number of the elements of the array
);

[ public ]
SFCError RegisterTracer(
    SFXEventRangeConstPtr range          // array of event range
    SFYTracer::OrderEnumConstPtr order   // array of processing order
    SFYTracer::StateEnumConstPtr state   // array of distributing condition
    BoolConstPtr overload                // array of overloading condition
    SInt32 length                        // number of the elements of the array
);

Argument

range: represent the event range to which the tracer rules adjust.
rule: represents the set of processing order, distributing condition, and overloading condition.

Return value

If succeeds: SFERR_NO_ERROR
If invalid parameter: SFERR_INVALID_PARAM
If insufficient memory: SFERR_NO_MEMORY

Description

This function registers specified dispatching rules into the tracer of this SFYDistributer instance.

If more than one dispatching rule for the same event are registered, only the last registered dispatching rule will be effective.

Example

SFYDistributer _distributer;
SFCError error;

register one dispatching rule into the tracer of a responder at a time
error = _distributer.RegisterTracer(SFXEventRange(SFEVT_APP_START, SFEVT_APP_START, SFP16_BEGIN, SFP16_END), SFYTracer::ORDER_BACKWARD, SFYTracer::STATE_ALL, true);


register more than one dispatching rule into the tracer of a responder at a time
static SFXEventRange::AtomRecConst range[] = {
    {     SFEVT_APP_START,    SFEVT_APP_START, SFP16_BEGIN, SFP16_END},
    {      SFEVT_APP_STOP,     SFEVT_APP_STOP, SFP16_BEGIN, SFP16_END},
    {    SFEVT_APP_RESUME,   SFEVT_APP_RESUME, SFP16_BEGIN, SFP16_END},
    {   SFEVT_APP_SUSPEND,  SFEVT_APP_SUSPEND, SFP16_BEGIN, SFP16_END}
};
static SFYTracer::RuleRecConst rule[lengthof(range)] = {
    {  SFYTracer::ORDER_BACKWARD,      SFYTracer::STATE_ALL,        true},
    {   SFYTracer::ORDER_FORWARD,      SFYTracer::STATE_ALL,        true},
    {  SFYTracer::ORDER_BACKWARD,      SFYTracer::STATE_ALL,        true},
    {   SFYTracer::ORDER_FORWARD,      SFYTracer::STATE_ALL,        true}
};

error = _distributer.RegisterTracer(atomic_cast(range), rule, lengthof(range));

Reference

SFYDistributer::Terminate

Terminate this distributer.

[ public ]
Void Terminate(Void);

Description

This function releases all the resources necessary for distributing an event to the responders of the responder tree bound with this distributer and terminates this distributer itself.

In case this distributer is bound with the responder tree, it is necessary to terminate all responders of the responder tree before calling this function.

Reference

SFYDistributer::UnregisterHandler

Unregister the handles from this distributer that match the specified condition.

[ public ]
Void UnregisterHandler(
    SFXEventRangeConstRef range        // event range
    SFYHandler::RuleRecConstRef rule   // handler rule
);

[ public ]
Void UnregisterHandler(
    SFXEventRangeConstRef range   // event range
    SFYHandler::HandlerSPP spp    // handler function
    VoidPtr reference             // reference value
);

[ public ]
Void UnregisterHandler(
    SFXEventRangeConstPtr range        // array of event range
    SFYHandler::RuleRecConstPtr rule   // array of handler rule
    SInt32 length                      // number of the elements of the array
);

[ public ]
Void UnregisterHandler(
    SFXEventRangeConstPtr range          // array of event range
    SFYHandler::HandlerSPPConstPtr spp   // array of handler function
    VoidPtrConstPtr reference            // array of reference value
    SInt32 length                        // number of the elements of the array
);

Argument

range: represents the range of events which the handler will receive.
rule: represents the set of handler functions and reference values.

Description

This function unregisters the handler from this SFYDistributer instance which matches the specified condition.

Only the handler which maches the specified condition on the event range and the handler rule will be unregistered.

If more than one handler of the same condition are registered, the last registered one will be unregistered.

Reference

SFYDistributer::UnregisterTracer

Unregister the dispatching rules from the tracer of this distributer which matches the specified condition.

[ public ]
Void UnregisterTracer(
    SFXEventRangeConstRef range   // event range
);

[ public ]
Void UnregisterTracer(
    SFXEventRangeConstPtr range   // array of event range
    SInt32 length                 // number of the elements of the array
);

Argument

range: represent the event range to which the tracer rules adjust.

Description

This function unregisters the dispatching rule from the tracer of this SFYDistributer instance which matches the specified condition.

Only the dispatching rule which maches the specified condition on event range will be unregistered from the tracer.

If more than one dispatching rule of the same condition are registered, the last registered one will be unregistered.

Reference