--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/mmuifw_plat/alf_widgetmodel_api/inc/alf/alfwidgeteventhandler.h Thu Dec 17 08:56:02 2009 +0200
@@ -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 <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
+