/*
* 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:   Widget control event handler interface.
*
*/


#ifndef I_ALFWIDGETEVENTHANDLER_H
#define I_ALFWIDGETEVENTHANDLER_H

#include <alf/ialfinterfacebase.h>
#include <alf/alftypes.h>


class TAlfEvent;

namespace duiuimodel
    {
class DuiNode;
    }
using namespace duiuimodel;

namespace Alf
    {
//FORWARD DECLARATIONS
class CAlfWidgetControl;
class AlfCustomInitDataBase; 
struct AlfWidgetEventHandlerInitData; 


namespace alfwidgeteventhandler
    {
static const IfId ident =
    {
    0, "alfwidgeteventhandler"
    };
    }
    
/**
 *  The interface for event handlers used by
 *  widget controls. The event handlers are
 *  used for handling any Alfred events, including
 *  key events, pointer events and custom events.
 *  Interfaces provided by the event handlers can
 *  be accessed using IAlfInterfaceBase::MakeInterface().
 *
 *  @lib alfwidgetmodel.lib
 *  @since S60 ?S60_version
 *  @status Draft
 */
class IAlfWidgetEventHandler : public IAlfInterfaceBase
    {
public:
    enum AlfEventHandlerType
        {
        /**
         * Presentation related event handlers. These will be deleted when the 
         * presentation is destroyed.
         * @see: IAlfWigetControl::destroyPresentation
         * @see: IAlfWiget::setPresentation
         */ 
        EPresentationEventHandler,
        /**
         * Logical event handlers. These event handlers are not presentation related and
         * will not be destroyed during the destruction of the presentation.
         */
        ELogicalEventHandler,   
        };
    
    /**
     * Phase in which event handlers are executed.
     */
    enum AlfEventHandlerExecutionPhase
        {
        /**
         * Tunneling event handlers are executed only in the tunnelling phase of the 
         * event handling cycle. Tunnelling event handlers are executed before
         * IAlfWidgetControl::HandleEvent is executed.
         * @see IAlfWidgetControl::HandleEvent
         */ 
        ETunnellingPhaseEventHandler,
    
        /**
         * Bubbling event handlers are executed only in the bubbling phase of the 
         * event handling cycle. Bubbling event handlers are executed after
         * IAlfWidgetControl::HandleEvent is executed.
         * @see IAlfWidgetControl::HandleEvent
         */ 
        EBubblingPhaseEventHandler,     
    
        /**
         * These event handlers are executed both in the tunneling and bubbling phase 
         * of the event handling cycle i.e both before and after IAlfWidgetControl::HandleEvent
         * is executed.
         * @see IAlfWidgetControl::HandleEvent
         */ 
        ETunnellingAndBubblingPhaseEventHandler,        
        };
        
    static inline const IfId& type()
        {
        return alfwidgeteventhandler::ident;
        }

    virtual inline ~IAlfWidgetEventHandler() {}

    /**
     * Used to identify event handlers that are capable of handling
     * a specified key or custom event. Pointer event handlers cannot be
     * identified directly, since they are dependent on the presentation.
     * Therefore, pointer event handlers should be associated with
     * a custom event ID that can be used to simulate the actual pointer event.
     *
     * @since S60 ?S60_version
     * @param aEvent The event.
     * @return <code>ETrue</code> if the event can be processed. Otherwise <code>EFalse</code>.
     */
    virtual bool accept( CAlfWidgetControl& aControl, const TAlfEvent& aEvent ) const = 0;

    /**
     * Called when an input event is being offered to this event handler.
     * The return value is used to indicate if the event was processed.
     * Processed events may not be offered to other event handlers.
     *
     * @since S60 ?S60_version
     * @param aControl The parent control of this event handler.
     * @param aEvent The event.
     * @return Result of event processing. See AlfEventStatus.
     */
    virtual AlfEventStatus offerEvent( CAlfWidgetControl& aControl,const TAlfEvent& aEvent) = 0;

    /**
     * Defines the widget states, where the event handler is active.
     * By default, if this method is not called, the event handler is expected
     * to be active in all states.
     *
     * @param aStates A bitmask defining the widget states, where the event
     * handler is active. The low 16 bits are reserved for the states
     * defined by the framework in . The high 16 bits are
     * available for states defined by the client code.
     */
    virtual void setActiveStates( unsigned int aStates ) = 0;
    
    /**
     * Sets AlfWidgetEventHandlerInitData to event handler.
     *
     * @param aData A data structure which contains for example id of the event
     * handler.
     */
    virtual void setEventHandlerData( const AlfWidgetEventHandlerInitData& aData ) = 0;
    
    /**
     * Returns AlfWidgetEventHandlerInitData.
     *
     * @return  A pointer to AlfWidgetEventHandlerInitData structure which contains
     * for example id of the event handler.
     */
    virtual AlfWidgetEventHandlerInitData* eventHandlerData() = 0;

    /**
     * Returns the type of EventHandler. 
     * @see IAlfWidgetEventHandler::AlfEventHandlerType
     *
     * @return The type of event handler.
     */
    virtual AlfEventHandlerType eventHandlerType() = 0;

    /**
     * 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.
     */
    virtual AlfEventHandlerExecutionPhase eventExecutionPhase() = 0;
    };

/**
 * Placeholder for information required to instantiate an event handler
 * via the widget factory mechanism.
 * A pointer to this structure is casted to a void pointer and sent to the
 * factory plugin.
 * @lib alfwidgetmodel.lib
 * @since S60 ?S60_version
 */
struct AlfWidgetEventHandlerInitData
    {
    /**
     * Event handler instance ID.This uniquely identifies every event handler instance.
     */
    char* mWidgetEventHandlerId;
    
    /**
     * Pointer to node in declaration containing information for the widget.
     */
    DuiNode* mNode;

    /**
     * Pointer to custom data passed via factory mechanism
     * Not Owned.
     */
    AlfCustomInitDataBase* mCustomData;  
    };

    } // namespace Alf

#endif // I_ALFWIDGETEVENTHANDLER_H

// End of File