1 /*

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

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

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

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:   Header for generic event handler for alf widgets

    15 *

    16 */

    17 

    18 

    19 #ifndef ALFWIDGETEVENTHANDLER_H

    20 #define ALFWIDGETEVENTHANDLER_H

    21 

    22 

    23 #include <osn/osndefines.h>

    24 #include <osn/osncommon.h>

    25 #include <alf/alfevent.h>

    26 #include <alf/alfcommand.h>

    27 #include <alf/ialfwidgeteventhandler.h>

    28 #include <alf/alfwidgetevents.h>

    29 using namespace osncore;

    30 

    31 #include <memory>

    32 using namespace std;

    33 

    34 namespace osncore

    35     {

    36 class UString;

    37     }

    38 

    39 using osncore::UString;

    40 

    41 namespace Alf

    42     {

    43 class CAlfWidgetControl;

    44 class AlfWidget;

    45 class AlfReferenceToVisual;

    46 class IAlfAttributeSetter;

    47 class AlfAttributeContainer;

    48 class AlfWidgetEventHandlerImpl;

    49 class AlfAttribute;

    50 class AlfAttributeValueType;

    51 class IfId;

    52 class IAlfEventOutputSignalSubscriber;

    53 class IAlfAppEventListener;

    54 

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

    56 enum

    57     {

    58     EActivateState = 1000000,

    59     EDeactivateState

    60     };

    61 

    62 enum WidgetTactileFeedbackType

    63     {

    64     tactileFeedbackNone,

    65     tactileFeedbackBasic,

    66     tactileFeedbackSensitive

    67     };

    68 

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

    70  *  A generic event handler for alf widgets.

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

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

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

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

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

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

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

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

    79  *

    80  *  @code

    81  *   ?good_class_usage_example(s)

    82  *  @endcode

    83  *

    84  *  @lib alfwidgetmodel.lib

    85  *  @since S60 ?S60_version

    86  *  @status Draft

    87  */

    88 OSN_NONSHARABLE_CLASS( AlfWidgetEventHandler ) :  public IAlfWidgetEventHandler

    89     {

    90 public:

    91 

    92     /**

    93      * Constructor.

    94      * @param IAlfWidgetEventHandler::AlfEventHandlerType type whe

    95      * @param aEventHandlerType            Event handler type. 

    96      *                                     It can be presentaion related or logical.

    97      * @param aEventHandlerExecutionPhase  Event handler exceution phase. 

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

    99      */

   100     OSN_IMPORT AlfWidgetEventHandler( 

   101                IAlfWidgetEventHandler::AlfEventHandlerType 

   102                        aEventHandlerType = ELogicalEventHandler,

   103                IAlfWidgetEventHandler::AlfEventHandlerExecutionPhase 

   104                        aEventHandlerExecutionPhase = ETunnellingPhaseEventHandler );

   105 

   106     /**

   107     * Destructor.

   108     */

   109     virtual ~AlfWidgetEventHandler();

   110 

   111     /**

   112      * Adds a key event input to the event handler.

   113      *

   114      * @exception std::bad_alloc     

   115      * @param aEventID The key code

   116      * @param aEventTypeFlags Event type flags.

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

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

   119      * See enumeration KeyEventModifiers for the possible bit values.

   120      */

   121     OSN_IMPORT void addKeyInput(

   122         int aEventID,

   123         EventTypeFlags aEventTypeFlags = keyDown,

   124         uint aKeyEventModifiers = 0 );

   125 

   126     /**

   127      * Adds a custom event input to the event handler.

   128      *

   129 	 * @exception std::bad_alloc     

   130      * @param aEventID The event ID.

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

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

   133      *                   aUseEventData is true.

   134      */

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

   136                                     int aEventData = 0 );

   137 

   138     /**

   139      * Adds a pointer event input in the event handler.

   140      *

   141 	 * @exception std::bad_alloc     

   142      * @param aElementName The name of the element.

   143      * @param aVisualName The name of the visual.

   144      * @param aEvent 

   145      */

   146     OSN_IMPORT void addPointerInput(

   147         const char* aElementName, const char* aVisualName, 

   148         WidgetPointerEvent aEvent = pointerEventUp );

   149 

   150     /**

   151      * Adds an event output in the event handler.

   152      *

   153 	 * @exception std::bad_alloc     

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

   155      * TAlfEvent::ETypeCustom and TAlfEvent::ETypeKey.

   156      * @param aEventID The event ID.

   157      * @param aTargetWidget The name of the target widget.

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

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

   160      * Key event outputs must always define a target widget.

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

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

   163      * Currently, key event outputs are always executed immediately.

   164      */

   165     OSN_IMPORT void addOutput(

   166         int aEventType,

   167         int aEventID,

   168         const char* aTargetWidget,

   169         unsigned int aDelay = 0 );

   170 

   171     /**

   172      * Adds an animation output in the event handler.

   173      *

   174 	 * @exception std::bad_alloc     

   175      * @param aTargetVisual Reference to the animated visual.

   176      * @param aReferenceVisual Reference to the visual with the

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

   178      *

   179      * @param aAttributeSetter The attribute setter for animating

   180      * the attribute using Hitchcock commands. Ownership is transferred,

   181      * if the method does not throw an exception.

   182      *

   183      * @param aAttributeContainer The attribute container holding the attribute

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

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

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

   187      * is triggered.

   188      *

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

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

   191      * corresponding attribute in the attribute container.

   192      *

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

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

   195      * corresponding attribute in the attribute container.

   196      */

   197     OSN_IMPORT void addAnimationOutput(

   198         AlfReferenceToVisual* aTargetVisual,

   199         AlfReferenceToVisual* aReferenceVisual,

   200         IAlfAttributeSetter* aAttributeSetter,

   201         AlfAttributeContainer* aAttributeContainer,

   202         unsigned int aAnimationTime,

   203         unsigned int aDelay );

   204 

   205     /**

   206      * Adds an event output for canceling timed custom events

   207      * in the event handler.

   208      *

   209 	 * @exception std::bad_alloc     

   210      * @param aTargetWidget The name of the target widget.

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

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

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

   214      * the aEventID parameter is ignored.

   215      */

   216     OSN_IMPORT void addCancelOutput(

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

   218 

   219     /**

   220      * Adds an event output for canceling timed animation events

   221      * in the event handler.

   222      *

   223 	 * @exception std::bad_alloc     

   224      * @param aElementName Element name.

   225      * @param aVisualName Visual name.

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

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

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

   229      * the aOperation parameter is ignored.

   230      */

   231     OSN_IMPORT void addAnimationCancelOutput(

   232         const char* aElementName,

   233         const char* aVisualName,

   234         TAlfOp aOperation,

   235         bool aCancelAll );

   236 

   237     /**

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

   239      * of the widget.

   240      *

   241 	 * @exception std::bad_alloc     

   242      * @param aAttribute The attribute

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

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

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

   246      */

   247     OSN_IMPORT void addWidgetAttributeOutput( AlfAttribute& aAttribute,

   248         const char* aWidgetId = 0 );

   249 

   250     /**

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

   252      * of the widget.

   253      *

   254 	 * @exception std::bad_alloc     

   255      * @param aName Name of the attribute

   256      * @param aValue Value of the attribute

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

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

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

   260      */

   261     OSN_IMPORT void addWidgetAttributeOutput( UString& aName,

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

   263             

   264     /**

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

   266      * of the widget.

   267      *

   268 	 * @exception std::bad_alloc     

   269      * @param aName Name of the attribute

   270      * @param aValue Value of the attribute

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

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

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

   274      */

   275     OSN_IMPORT void addWidgetAttributeInput( UString& aName,

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

   277 

   278     /**

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

   280      * Note that the implementation of this function is flagged

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

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

   283      *

   284 	 * @exception std::bad_alloc     

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

   286      * be used in the output.

   287      */

   288     OSN_IMPORT void addTactileOutput( 

   289         WidgetTactileFeedbackType aFeedbackType );

   290 

   291     /**

   292      * Adds an event output for event passing.

   293      *

   294      * @param aSourceWidget

   295      * @param aTargetWidget 

   296      * be used in the output.

   297      */

   298     OSN_IMPORT void addEventPasserOutput( 

   299     	const char* aSourceWidget , const char* aTargetWidget );	

   300     	

   301     /**

   302      * Adds an event output for event passing. 

   303      *

   304      * @param aSourceWidget defines source widget

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

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

   307      * @param aNewEventCustomData New event custom data

   308      * be used in the output.

   309      */

   310     OSN_IMPORT void addEventPasserOutput( 

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

   312     /**

   313      * Adds an event input for event passing. 

   314      * @param aEventId integer contains the specific event id. 

   315      * @param aCustomData Event specific integer data

   316      */		

   317     OSN_IMPORT void addEventPasserInput (

   318 	    int aEventId, int aCustomData );

   319     /**

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

   321      *

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

   323      * its callback method.

   324      */

   325     OSN_IMPORT void addWidgetEventOutputSignalSubscriber( IAlfEventOutputSignalSubscriber& aSubscriber );

   326 

   327     /**

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

   329      *

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

   331      *     if aTargetWidget is NULL or empty.

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

   333      *     if aDisableStates and aEnableStates have a common bit set. 

   334      *

   335 	 * @exception std::bad_alloc     

   336      * @param aName Id of the target widget instance

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

   338      * @param aDisableStates mask of states to be cleared

   339      */

   340     OSN_IMPORT void addWidgetStateOutput( const UString& aTargetWidget,

   341         uint aEnableStates, uint aDisableStates );     

   342         

   343     /**

   344      * Adds application event output for event passing.

   345      *

   346      * @exception std::bad_alloc

   347      * @param aCmd command

   348      * @param aAppEvent subscriber

   349      */

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

   351 

   352 // from base class IAlfWidgetEventHandler

   353 

   354     /**

   355      * @see IAlfWidgetEventHandler.

   356      */

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

   358 

   359 

   360     /**

   361      * @see IAlfWidgetEventHandler.

   362      */

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

   364 

   365     /**

   366      * @see IAlfWidgetEventHandler.

   367      */

   368     void setActiveStates( unsigned int aStates );

   369 

   370     /**

   371      * @see IAlfWidgetEventHandler.

   372      */

   373     void setCapturing( bool aCapturing );

   374 

   375     /**

   376      * @see IAlfWidgetEventHandler.

   377      */

   378     bool capturing() const;

   379     

   380     /**

   381      * @see IAlfWidgetEventHandler.

   382      * Calls to this API will overwrite previous set values.

   383      */

   384     void setEventHandlerData( const AlfWidgetEventHandlerInitData& aData );

   385     

   386     /**

   387      * @see IAlfWidgetEventHandler.

   388      */

   389     AlfWidgetEventHandlerInitData* eventHandlerData();

   390 

   391     /**

   392      * Returns the type of EventHandler. 

   393      * @see IAlfWidgetEventHandler::AlfEventHandlerType

   394      *

   395      * @return The type of event handler.

   396      */

   397     IAlfWidgetEventHandler::AlfEventHandlerType eventHandlerType();

   398 

   399     /**

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

   401      * which the event hadler will be executed.

   402      * @see IAlfWidgetEventHandler::AlfEventHandlerExecutionPhase

   403      *

   404      * @return Event handler execution phase.

   405      */

   406     IAlfWidgetEventHandler::AlfEventHandlerExecutionPhase eventExecutionPhase();

   407 

   408 // from base class IAlfInterfaceBase

   409 

   410     /**

   411      * @see IAlfInterfaceBase.

   412      */

   413     IAlfInterfaceBase* makeInterface( const IfId& aType );

   414 

   415 

   416 private: // data

   417 

   418     auto_ptr<AlfWidgetEventHandlerImpl> mImpl;

   419     };

   420 

   421     } // namespace Alf

   422 

   423 #endif // C_ALFWIDGETEVENTHANDLER_H

   424