diff -r 4ea6f81c838a -r 0e9bb658ef58 mmuifw_plat/alf_widgetmodel_api/inc/alf/alfwidgeteventhandler.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mmuifw_plat/alf_widgetmodel_api/inc/alf/alfwidgeteventhandler.h Wed Sep 01 12:23:18 2010 +0100 @@ -0,0 +1,424 @@ +/* +* 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 +#include +#include +#include +#include +#include +using namespace osncore; + +#include +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 mImpl; + }; + + } // namespace Alf + +#endif // C_ALFWIDGETEVENTHANDLER_H +