/*

* 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