/*

* Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies). 

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:   Header for generic event handler for alf widgets

*

*/

#ifndef ALFWIDGETEVENTHANDLER_H

#define ALFWIDGETEVENTHANDLER_H

#include <osn/osndefines.h>

#include <osn/osncommon.h>

#include <alf/alfevent.h>

#include <alf/alfcommand.h>

#include <alf/ialfwidgeteventhandler.h>

#include <alf/alfwidgetevents.h>

using namespace osncore;

#include <memory>

using namespace std;

namespace osncore

    {

class UString;

    }

using osncore::UString;

namespace Alf

    {

class CAlfWidgetControl;

class AlfWidget;

class AlfReferenceToVisual;

class IAlfAttributeSetter;

class AlfAttributeContainer;

class AlfWidgetEventHandlerImpl;

class AlfAttribute;

class AlfAttributeValueType;

class IfId;

class IAlfEventOutputSignalSubscriber;

class IAlfAppEventListener;

// Custom event IDs defined by the event handling framework.

enum

    {

    EActivateState = 1000000,

    EDeactivateState

    };

enum WidgetTactileFeedbackType

    {

    tactileFeedbackNone,

    tactileFeedbackBasic,

    tactileFeedbackSensitive

    };

/** @class AlfWidgetEventHandler alfwidgeteventhandler.h "alf/alfwidgeteventhandler.h"

 *  A generic event handler for alf widgets.

 *  One AlfWidgetEventHandler instance is meant to handle one or more event

 *  inputs, which result in the same event output. When any of the event inputs

 *  accept the given event, all the event outputs and event cancel outputs are

 *  executed. However, animation event outputs and cancel outputs are executed

 *  only in response to custom events, not pointer or key events.

 *  If an animation command is required in response to a key or pointer event,

 *  the event handler handling those should generate a custom event and then

 *  the event handler handling that should generate an animation command.

 *

 *  @code

 *   ?good_class_usage_example(s)

 *  @endcode

 *

 *  @lib alfwidgetmodel.lib

 *  @since S60 ?S60_version

 *  @status Draft

 */

OSN_NONSHARABLE_CLASS( AlfWidgetEventHandler ) :  public IAlfWidgetEventHandler

    {

public:

    /**

     * Constructor.

     * @param IAlfWidgetEventHandler::AlfEventHandlerType type whe

     * @param aEventHandlerType            Event handler type. 

     *                                     It can be presentaion related or logical.

     * @param aEventHandlerExecutionPhase  Event handler exceution phase. 

     *                                     It can be tunneling phase/bubbling phase/both.   

     */

    OSN_IMPORT AlfWidgetEventHandler( 

               IAlfWidgetEventHandler::AlfEventHandlerType 

                       aEventHandlerType = ELogicalEventHandler,

               IAlfWidgetEventHandler::AlfEventHandlerExecutionPhase 

                       aEventHandlerExecutionPhase = ETunnellingPhaseEventHandler );

    /**

    * Destructor.

    */

    virtual ~AlfWidgetEventHandler();

    /**

     * Adds a key event input to the event handler.

     *

     * @exception std::bad_alloc     

     * @param aEventID The key code

     * @param aEventTypeFlags Event type flags.

     * @param aKeyEventModifiers Bitmask of the possible modifiers of the key event.

     * This event handler is triggered only if the received key event contains these modifiers.

     * See enumeration KeyEventModifiers for the possible bit values.

     */

    OSN_IMPORT void addKeyInput(

        int aEventID,

        EventTypeFlags aEventTypeFlags = keyDown,

        uint aKeyEventModifiers = 0 );

    /**

     * Adds a custom event input to the event handler.

     *

	 * @exception std::bad_alloc     

     * @param aEventID The event ID.

     * @param aUseEventData Use the custom event data to determine the accepted events.

     * @param aEventData The accepted custom event data value. Only used if

     *                   aUseEventData is true.

     */

    OSN_IMPORT void addCustomInput( int aEventID, bool aUseEventData = EFalse,

                                    int aEventData = 0 );

    /**

     * Adds a pointer event input in the event handler.

     *

	 * @exception std::bad_alloc     

     * @param aElementName The name of the element.

     * @param aVisualName The name of the visual.

     * @param aEvent 

     */

    OSN_IMPORT void addPointerInput(

        const char* aElementName, const char* aVisualName, 

        WidgetPointerEvent aEvent = pointerEventUp );

    /**

     * Adds an event output in the event handler.

     *

	 * @exception std::bad_alloc     

     * @param aEventType The event type. The only accepted types are

     * TAlfEvent::ETypeCustom and TAlfEvent::ETypeKey.

     * @param aEventID The event ID.

     * @param aTargetWidget The name of the target widget.

     * In the case of custom events, it can be an empty string, which means

     * that the event is to be broadcast to all the event handlers.

     * Key event outputs must always define a target widget.

     * @param aDelay Delay in microseconds before sending the command.

     * The default value of zero means that the command is scheduled immediately.

     * Currently, key event outputs are always executed immediately.

     */

    OSN_IMPORT void addOutput(

        int aEventType,

        int aEventID,

        const char* aTargetWidget,

        unsigned int aDelay = 0 );

    /**

     * Adds an animation output in the event handler.

     *

	 * @exception std::bad_alloc     

     * @param aTargetVisual Reference to the animated visual.

     * @param aReferenceVisual Reference to the visual with the

     * reference value, or NULL if no reference value is used.

     *

     * @param aAttributeSetter The attribute setter for animating

     * the attribute using Hitchcock commands. Ownership is transferred,

     * if the method does not throw an exception.

     *

     * @param aAttributeContainer The attribute container holding the attribute

     * value(s) used by the attribute setter. Ownership is transferred, if the method does not

     * throw an exception. The container can hold new values for multiple different

     * attributes, in which case all of them are applied when the animation output

     * is triggered.

     *

     * @param aAnimationTime The duration of the animation. Note that this parameter

     * is used only if the transition time parameter is not defined in the

     * corresponding attribute in the attribute container.

     *

     * @param aDelay The delay in microseconds before starting the animation.

     * Note that this parameter is used only if the delay parameter is not defined in the

     * corresponding attribute in the attribute container.

     */

    OSN_IMPORT void addAnimationOutput(

        AlfReferenceToVisual* aTargetVisual,

        AlfReferenceToVisual* aReferenceVisual,

        IAlfAttributeSetter* aAttributeSetter,

        AlfAttributeContainer* aAttributeContainer,

        unsigned int aAnimationTime,

        unsigned int aDelay );

    /**

     * Adds an event output for canceling timed custom events

     * in the event handler.

     *

	 * @exception std::bad_alloc     

     * @param aTargetWidget The name of the target widget.

     * @param aEventID The event ID of the event to be canceled.

     * @param aCancelAll Whether to cancel all the custom commands that are

     * scheduled to be sent to the widget or not. If this is ETrue,

     * the aEventID parameter is ignored.

     */

    OSN_IMPORT void addCancelOutput(

        const char* aTargetWidget, int aEventID, bool aCancelAll );

    /**

     * Adds an event output for canceling timed animation events

     * in the event handler.

     *

	 * @exception std::bad_alloc     

     * @param aElementName Element name.

     * @param aVisualName Visual name.

     * @param aOperation Identifies the operation of the command to be canceled.

     * @param aCancelAll Whether to cancel all the animation commands that are

     * scheduled to be sent to the widget or not. If this is ETrue,

     * the aOperation parameter is ignored.

     */

    OSN_IMPORT void addAnimationCancelOutput(

        const char* aElementName,

        const char* aVisualName,

        TAlfOp aOperation,

        bool aCancelAll );

    /**

     * Adds an event output for changing the value of a certain attribute

     * of the widget.

     *

	 * @exception std::bad_alloc     

     * @param aAttribute The attribute

     * object is transferred and this function takes care of deleting it

     * even if the function leaves. Thus, it should not be in the cleanup stack

     * when calling this function, to avoid potential double deletion.

     */

    OSN_IMPORT void addWidgetAttributeOutput( AlfAttribute& aAttribute,

        const char* aWidgetId = 0 );

    /**

     * Adds an event output for changing the value of a certain attribute

     * of the widget.

     *

	 * @exception std::bad_alloc     

     * @param aName Name of the attribute

     * @param aValue Value of the attribute

     * object is transferred and this function takes care of deleting it

     * even if the function leaves. Thus, it should not be in the cleanup stack

     * when calling this function, to avoid potential double deletion.

     */

    OSN_IMPORT void addWidgetAttributeOutput( UString& aName,

        AlfAttributeValueType* aValue, const char* aWidgetId = 0 );

    /**

     * Adds an event output for changing the value of a certain attribute

     * of the widget.

     *

	 * @exception std::bad_alloc     

     * @param aName Name of the attribute

     * @param aValue Value of the attribute

     * object is transferred and this function takes care of deleting it

     * even if the function leaves. Thus, it should not be in the cleanup stack

     * when calling this function, to avoid potential double deletion.

     */

    OSN_IMPORT void addWidgetAttributeInput( UString& aName,

        AlfAttributeValueType* aValue, const char* aElementId = 0 );

    /**

     * Adds an event output for launching tactile feedback (instant feedback).

     * Note that the implementation of this function is flagged

     * with RD_TACTILE_FEEDBACK, i.e. if RD_TACTILE_FEEDBACK is not defined

     * the method does nothing --> no output added.

     *

	 * @exception std::bad_alloc     

     * @param aFeedbackType The type of the tactile feedback that should 

     * be used in the output.

     */

    OSN_IMPORT void addTactileOutput( 

        WidgetTactileFeedbackType aFeedbackType );

    /**

     * Adds an event output for event passing.

     *

     * @param aSourceWidget

     * @param aTargetWidget 

     * be used in the output.

     */

    OSN_IMPORT void addEventPasserOutput( 

    	const char* aSourceWidget , const char* aTargetWidget );	

    /**

     * Adds an event output for event passing. 

     *

     * @param aSourceWidget defines source widget

     * @param aTargetWidget defines target widget. ie. Event is offered for the target widget

     * @param aNewEventId Event is mapped to this type of event.

     * @param aNewEventCustomData New event custom data

     * be used in the output.

     */

    OSN_IMPORT void addEventPasserOutput( 

      const char* aSourceWidget , const char* aTargetWidget, int aNewEventId, int aNewEventCustomData );

    /**

     * Adds an event input for event passing. 

     * @param aEventId integer contains the specific event id. 

     * @param aCustomData Event specific integer data

     */		

    OSN_IMPORT void addEventPasserInput (

	    int aEventId, int aCustomData );

    /**

     * Adds a subscriber to be notified when event handler's input is received.

     *

     * @param aSubscriber Object containing knowledge of the subscribing class and 

     * its callback method.

     */

    OSN_IMPORT void addWidgetEventOutputSignalSubscriber( IAlfEventOutputSignalSubscriber& aSubscriber );

    /**

     * Adds an event output for changing the state of a widget

     *

     * @exception Alf::AlfWidgetException value osncore::EInvalidWidget 

     *     if aTargetWidget is NULL or empty.

     * @exception Alf::AlfWidgetException value osncore::EInvalidArgument 

     *     if aDisableStates and aEnableStates have a common bit set. 

     *

	 * @exception std::bad_alloc     

     * @param aName Id of the target widget instance

     * @param aEnableStates mask of states to be set to true

     * @param aDisableStates mask of states to be cleared

     */

    OSN_IMPORT void addWidgetStateOutput( const UString& aTargetWidget,

        uint aEnableStates, uint aDisableStates );     

    /**

     * Adds application event output for event passing.

     *

     * @exception std::bad_alloc

     * @param aCmd command

     * @param aAppEvent subscriber

     */

    OSN_IMPORT void addAppEventOutput(const UString& aCmd , IAlfAppEventListener& aAppEvent ); 

// from base class IAlfWidgetEventHandler

    /**

     * @see IAlfWidgetEventHandler.

     */

    virtual AlfEventStatus offerEvent( CAlfWidgetControl& aControl,const TAlfEvent& aEvent);

    /**

     * @see IAlfWidgetEventHandler.

     */

    bool accept( CAlfWidgetControl& aControl, const TAlfEvent& aEvent ) const;

    /**

     * @see IAlfWidgetEventHandler.

     */

    void setActiveStates( unsigned int aStates );

    /**

     * @see IAlfWidgetEventHandler.

     */

    void setCapturing( bool aCapturing );

    /**

     * @see IAlfWidgetEventHandler.

     */

    bool capturing() const;

    /**

     * @see IAlfWidgetEventHandler.

     * Calls to this API will overwrite previous set values.

     */

    void setEventHandlerData( const AlfWidgetEventHandlerInitData& aData );

    /**

     * @see IAlfWidgetEventHandler.

     */

    AlfWidgetEventHandlerInitData* eventHandlerData();

    /**

     * Returns the type of EventHandler. 

     * @see IAlfWidgetEventHandler::AlfEventHandlerType

     *

     * @return The type of event handler.

     */

    IAlfWidgetEventHandler::AlfEventHandlerType eventHandlerType();

    /**

     * Returns information about the phase in the event handling cycle in

     * which the event hadler will be executed.

     * @see IAlfWidgetEventHandler::AlfEventHandlerExecutionPhase

     *

     * @return Event handler execution phase.

     */

    IAlfWidgetEventHandler::AlfEventHandlerExecutionPhase eventExecutionPhase();

// from base class IAlfInterfaceBase

    /**

     * @see IAlfInterfaceBase.

     */

    IAlfInterfaceBase* makeInterface( const IfId& aType );

private: // data

    auto_ptr<AlfWidgetEventHandlerImpl> mImpl;

    };

    } // namespace Alf

#endif // C_ALFWIDGETEVENTHANDLER_H