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:  The base class for all widget controls.

    15 *

    16 */

    17 

    18 

    19 #ifndef ALFWIDGETCONTROL_H

    20 #define ALFWIDGETCONTROL_H

    21 

    22 #include <osn/osndefines.h>

    23 #include <osn/osnnew.h> // for OSN operator new parameter types

    24 #include <alf/ialfwidgetcontrol.h>

    25 #include <alf/alfcontrol.h>

    26 #include <alf/ialfmodelchangeobserver.h>

    27 #include <memory>

    28 namespace osncore

    29     {

    30 template <class T> class AlfPtrVector;

    31     }

    32 

    33 namespace std

    34     {

    35 template <class T> class auto_ptr;

    36     }

    37 

    38 using namespace osncore;

    39 using namespace std;

    40 

    41 namespace Alf

    42     {

    43 class IAlfContainerWidget;

    44 class IAlfWidgetEventHandler;

    45 class IAlfElement;

    46 class AlfWidget;

    47 class IAlfMap;

    48 class IAlfVariantType;

    49 class AlfWidgetControlImpl;

    50 class IAlfHostAPI;

    51 class IfId;

    52 class ElementData;

    53 

    54 /** @class CAlfWidgetControl alfwidgetcontrol.h "alf/alfwidgetcontrol.h"

    55  *  The base class for all widget controls.

    56  *  Widget controls are derived from Alfred controls, and owned by

    57  *  the Alfred environment or control groups. Controls are responsible

    58  *  for the widget logic, i.e., storing and controlling the state of

    59  *  the widget. This usually includes input event handling, updating

    60  *  the presentation, and communication with the model, the application,

    61  *  and other controls. Event handlers can be used to implement parts

    62  *  of the widget logic.

    63  *

    64  *  @interfaces IAlfWidgetControl, IAlfHostAPI, IAlfAttributeOwner

    65  *  @lib alfwidgetmodel.lib

    66  *  @since S60 ?S60_version

    67  *  @status Draft

    68  */

    69 class CAlfWidgetControl :

    70             public CAlfControl,

    71             public IAlfModelChangeObserver,

    72             public IAlfWidgetControl

    73     {

    74 public:

    75 

    76     /**

    77      * The constructor.

    78      *

    79      * @since S60 ?S60_version

    80      * @param aEnv      The Alfred environment.

    81      */

    82     OSN_IMPORT CAlfWidgetControl(CAlfEnv& aEnv);

    83 

    84 

    85     /**

    86      * operator new method to ensure correct OS-neutral handling of failure to

    87      * allocate memory.

    88      *

    89      * This operator will throw std::bad_alloc if memory cannot be allocated.

    90      * If memory is successfully allocated, it will fill all bytes of allocated

    91      * memory with zero.

    92      * 

    93      * Note that the parameter list below is not relevant to the actual usage 

    94      * which is typically:

    95      *

    96      *   auto_ptr<CAlfWidgetControl> control(new(EMM) CAlfWidgetControl(aEnv));

    97      * or

    98      *   CAlfWidgetControl* mControl = new(EMM) CAlfWidgetControl(aEnv);

    99      * 

   100      * @exception Throws std::bad_alloc if there is a failure to allocate 

   101      *                memory for the object under construction.

   102      *

   103      * @param aSize The number of bytes required for an instance of the class.

   104      *            This parameter is supplied automatically.

   105      * @param aEnumValue An enumeration value of newarg. Always use EMM.

   106      * @return a pointer to the zero-ed memory allocated on the heap. 

   107      *             Ownership transferred to caller.

   108      */

   109     OSN_IMPORT void* operator new(size_t aSize, newarg aEnumValue) 

   110                                   throw (std::bad_alloc);

   111 

   112     /**

   113      * Destructor.

   114      */

   115     OSN_IMPORT virtual ~CAlfWidgetControl();

   116 

   117     /**

   118      * Set the owner widget of this control.

   119      * Called by AlfWidget::setControlL().

   120      *

   121      * @since S60 ?S60_version

   122      * @param aWidget The owner widget of this control.

   123      */

   124     void setOwnerWidget( AlfWidget* aWidget );

   125     

   126     /**

   127      * Returns top level layout. Returns NULL if this control does not

   128      * 

   129      * @return Pointer to top level layout, or NULL if not available.

   130      */

   131     OSN_IMPORT CAlfLayout* ContainerLayout(

   132                    const CAlfControl* /*aConnected*/) const;

   133     

   134     /**

   135      * state.

   136      */

   137     OSN_IMPORT uint state() const;

   138     

   139     /**

   140      * sets the state.

   141      */

   142     OSN_IMPORT void setState( uint aState );

   143     

   144     /**

   145      * enables State.

   146      */

   147     OSN_IMPORT void enableState( uint aState );

   148     

   149     /**

   150      * disables State.

   151      */

   152     OSN_IMPORT void disableState( uint aState );

   153     

   154     /**

   155      * checks  State.

   156      */

   157     OSN_IMPORT bool checkState( uint aState ) const;

   158     

   159     /**

   160      * returns no of event handlers.

   161      */

   162     OSN_IMPORT int numEventHandlers() const;

   163     

   164     /**

   165      * returns the event handlers at the index.

   166      */

   167     OSN_IMPORT IAlfWidgetEventHandler& eventHandler( int aIndex );

   168     

   169     /**

   170      * returns event handler index.

   171      */

   172     OSN_IMPORT int eventHandlerIndex(

   173                    IAlfWidgetEventHandler& aEventHandler ) const;

   174     

   175     /**

   176      * returns finds the event handler .

   177      */

   178     OSN_IMPORT IAlfWidgetEventHandler* findEventHandler(

   179                    const TAlfEvent& aEvent );

   180     

   181     /**

   182      * adds an event handler.

   183      * @exception osncore::AlfWidgetException Thrown with the error code 

   184      *     osncore::ECommonError when user tries to add an event handler at an

   185      *     index but it fails.

   186      */

   187     OSN_IMPORT void addEventHandler(

   188                    IAlfWidgetEventHandler* aEventHandler,

   189                    int aIndex = -1 );

   190     

   191     /**

   192      * removes an event handlers.

   193      */

   194     OSN_IMPORT void removeAndDestroyEventHandler(

   195                    IAlfWidgetEventHandler& aEventHandler );

   196     

   197     /**

   198      * returns no of event handlers.

   199      */

   200     OSN_IMPORT void removeEventHandler(

   201                    IAlfWidgetEventHandler& aEventHandler );

   202     

   203     /**

   204      * Remove and destroy an event handler from the control bases on its name.

   205      *

   206      * @since S60 ?S60_version

   207      * @param aHandlerId The name/Id of the event handler to be removed

   208      *                   and destroyed.

   209      */

   210     OSN_IMPORT void removeAndDestroyEventHandler( const UString& aHandlerId );

   211     

   212     /**

   213      * Remove and destroy an event handler from the control bases on its name.

   214      *

   215      * @since S60 ?S60_version

   216      * @param aHandlerId The name/Id of the event handler to be removed 

   217      *                   and destroyed.

   218      */

   219     OSN_IMPORT void removeAndDestroyEventHandler( UString& aHandlerId );

   220     

   221     /**

   222      * Remove and destroy all event handlers associated with presentation 

   223      * elements.

   224      * @since S60 ?S60_version

   225      */

   226     OSN_IMPORT void removeAndDestroyPresentationEventHandlers();

   227     

   228     /**

   229      * Removes all event handlers associated with presentation elements from 

   230      * this control.

   231      *

   232      * @since S60 ?S60_version

   233      */

   234     OSN_IMPORT void removePresentationEventHandlers();

   235     

   236     /**

   237      * Returns no of elements.

   238      */

   239     OSN_IMPORT int numElements() const;

   240     

   241     /**

   242      * Returns an element at the index.

   243      */

   244     OSN_IMPORT IAlfElement& element( int aIndex );

   245     

   246     /**

   247      * Finds an element with specified name.

   248      */

   249     OSN_IMPORT IAlfElement* findElement( const char* aName );

   250     

   251     /**

   252      * Adds an element in the end.

   253      * @exception std::bad_alloc

   254      * @exception osncore::AlfException Thrown with the error code 

   255      *     osncore::ECommonError if the given element object has been added 

   256      *     in the widget control already.

   257      *

   258      * @param aElement Element to be added.

   259      * Ownership is transferred iff no exception is thrown.

   260      */

   261     OSN_IMPORT void addElement( IAlfElement* aElement );

   262     

   263     /**

   264      * removes and destroys an element.

   265      */

   266     OSN_IMPORT void removeAndDestroyElement( const IAlfElement& aElement );

   267 

   268    /**

   269      * removes an element but does not destroy it.

   270      */

   271     OSN_IMPORT void removeElement( const IAlfElement& aElement ); 

   272        

   273     /**

   274      * Returns the data id of an element.

   275      */

   276     OSN_IMPORT virtual uint elementDataId(

   277                            const IAlfElement& aElement,

   278                            uint aIndex,

   279                            uint aParentDataId );

   280     

   281     /**

   282      * Returns the data id of the parent element of an element.

   283      */

   284     OSN_IMPORT virtual uint parentElementDataId(

   285                            const IAlfElement& aElement,

   286                            uint aDataId );

   287     

   288     /**

   289      * Returns index corresponding to a data id.

   290      */

   291     OSN_IMPORT virtual uint dataIdToIndex(

   292                            const IAlfElement& aElement,

   293                            uint aDataId );

   294     

   295     /**

   296      * Returns data of an element.

   297      */

   298     OSN_IMPORT IAlfVariantType* elementData(

   299                    const IAlfElement& aElement,

   300                    uint aDataId );

   301     

   302     /**

   303      * Sets the data id range of an element.

   304      */

   305     OSN_IMPORT void setDataIdRange( const IAlfElement& aElement, uint aRange );

   306     

   307     /**

   308      * Returns the data id range of an element.

   309      */

   310     OSN_IMPORT uint dataIdRange( const IAlfElement& aElement );

   311     

   312     /**

   313      * Updates presentation.

   314      * @exception osncore::AlfVisualException Thrown with the error code

   315      *    osncore::ECanNotCreateVisual when during updation of presentation, 

   316      *    visual trees are created and an error occurs during the creation of

   317      *    visuals.

   318      * @since S60 ?S60_version

   319      */

   320     OSN_IMPORT void updatePresentation();

   321     

   322     /**

   323      * Destroys presentation (visual trees under elements).

   324      */

   325     OSN_IMPORT void destroyPresentation( int aTimeMilliseconds = 0 );

   326     

   327     /**

   328      * Destroys all visuals and elements.

   329      */

   330     OSN_IMPORT void destroyVisualsAndElements( int aTimeMilliseconds = 0 ); 

   331     

   332     /**

   333      * Return the owner widget of this control .

   334      */

   335     OSN_IMPORT AlfWidget* widget();

   336 

   337     /*

   338      * Notifies the parent control that the layout should be recalculated.

   339      * If there is no parent, nothing is done.

   340      */

   341     OSN_IMPORT void updateParentLayout();

   342     

   343     /*

   344      * @return true if the control acts as a container for other widgets.

   345      * 

   346      */

   347     OSN_IMPORT bool isContainer() const;

   348     

   349     /*

   350      * @return true if the control is focusable, false otherwise.

   351      */

   352     OSN_IMPORT bool isFocusable() const;

   353     

   354     /**

   355      * Template getter for interfaces provided by the control classes.

   356      * The type of the queried interface is specified by the

   357      * template parameter.

   358      *

   359      * @exception std::bad_alloc 

   360      *

   361      * @since S60 ?S60_version

   362      * @param aControl The control to get the interface for.

   363      *

   364      * @return The queried interface, or NULL if the interface is not

   365      *         supported or available.

   366      */

   367     template <class T>

   368     static T* makeInterface( CAlfWidgetControl* aControl );

   369 

   370     /**

   371      * Handles events sent to widget control.

   372      * <b> Widgets can override this. </b>

   373      * The default implementation tunnels key events towards the 

   374      * focussed child widget. If custom events EEventFocusNextWidget/

   375      * EEventFocusPreviousWidget are received the default implementation

   376      * attempts to switch focus to the next/previous child widget.

   377      * 

   378      * @since S60 ?S60_version

   379      * @param aEvent The event to be handled.

   380      *

   381      * @return Result of event processing. See AlfEventStatus.

   382      */

   383     OSN_IMPORT virtual AlfEventStatus handleEvent( const TAlfEvent& aEvent );

   384     

   385     /**

   386      * Processes the events sent to this control.

   387      * The events are passed to the tunnelling phase event handlers,

   388      * handleEvent method and the bubbling phase event handlers in 

   389      * that order till one of them consumes the event.

   390      *

   391      * @since S60 ?S60_version

   392      * @param aEvent The event to be handled.

   393      *

   394      * @return Result of event processing. See AlfEventStatus.

   395      */

   396     OSN_IMPORT AlfEventStatus processEvent( const TAlfEvent& aEvent );

   397 

   398 // from base class IAlfModelChangeObserver

   399 

   400     /**

   401      * From IAlfInterfaceBase.

   402      * Update the control according to the changed model.

   403      * Destroy existing visuals and cancel all animation commands. 

   404      * Create new visuals according to the data in the new model.

   405      *

   406      * @since S60 ?S60_version

   407      * @param aModel The new model.

   408      */

   409     OSN_IMPORT virtual void modelChanged( IAlfModel& aModel );

   410 

   411     /**

   412      * Update the presentation according to the data changes.

   413      *

   414      * @since S60 ?S60_version

   415      * @param aArrayOfOperation An Array containing the operations performed 

   416      *                          on the model.

   417      */

   418     OSN_IMPORT virtual void dataChanging(

   419                           const AlfPtrVector<AlfModelOperation>& aOperations );

   420 

   421     /**

   422      * Update the presentation according to the data changes.

   423      *

   424      * @exception osncore::AlfVisualException Thrown with the error code 

   425      *     osncore::ECanNotCreateVisual when adding the visual tree through

   426      *     adding the data for it in the model but the creation of visual tree

   427      *     is failed.

   428      *

   429      * @since S60 ?S60_version

   430      * @param aOperation An operation performed on the model.

   431      */

   432     OSN_IMPORT virtual void dataChanging(

   433                            const AlfModelOperation& aOperation );

   434 

   435     /**

   436      * The default implementation is empty.

   437      * Derived classes may update the state of the

   438      * control according to the changed data.

   439      *

   440      * @since S60 ?S60_version

   441      */

   442     OSN_IMPORT virtual void dataChanged();

   443 

   444 // from base class IAlfInterfaceBase

   445 

   446     /**

   447      * From IAlfInterfaceBase.

   448      * Getter for interfaces provided by the control classes.

   449      * Derived classes should always call the base class method

   450      * from the overridden MakeInterface.

   451      *

   452      * @since S60 ?S60_version

   453      * @param aType A descriptor to identify the type of the queried interface.

   454      *

   455      * @return The queried interface, or NULL if the interface is not

   456      *         supported or available.

   457      */

   458     OSN_IMPORT virtual IAlfInterfaceBase* makeInterface( const IfId& aType );

   459 

   460 public:

   461 

   462 // New non-virtual methods

   463 

   464     /**

   465      * Resets control group of this control. If the control is in a

   466      * control group it will be removed from its currect control group

   467      * and appended to the given control group.

   468      *

   469      * @param Reference to the control group to which this control is appended.

   470      */

   471     void resetControlGroup(CAlfControlGroup& aControlGroup);

   472 

   473     /**

   474      * Resets control group of this control and the whole hierarchy of

   475      * controls that are connected to this control or its children with

   476      * connections.

   477      *

   478      * This control and the tree of controls below it are removed from

   479      * their previous control groups.

   480      *

   481      * @since S60 ?S60_version

   482      * @param Reference to the control group to which controls are appended.

   483      *        This control group replaces control groups to which the controls

   484      *        in this control hierarchy belong before the call is made.

   485      */

   486     void resetHierarchyControlGroup(CAlfControlGroup& aControlGroup);

   487     

   488     /**

   489      * Attempt to acquire focus for this control.

   490      */

   491     OSN_IMPORT void AcquireFocus();

   492     

   493     /**

   494      * Attempt to relinquish focus for this control.

   495      */ 

   496     OSN_IMPORT void RelinquishFocus();

   497     

   498     /**

   499      * returns hostApi for this control.

   500      * 

   501      * @return hostApi-instance.

   502      */

   503     IAlfHostAPI& hostAPI();

   504 

   505 protected:

   506 

   507     /**

   508      * The protected constructor.

   509      *

   510      * @since S60 ?S60_version

   511      */

   512     OSN_IMPORT CAlfWidgetControl();

   513 

   514 

   515     /**

   516      * The constructor.

   517      *

   518      * @since S60 ?S60_version

   519      * @param aEnv The Alfred environment.

   520      */

   521     OSN_IMPORT void construct(CAlfEnv& aEnv);

   522     

   523     /**

   524      * handles focusing to next control. 

   525      * Handles the container inside container cases. If next focusable

   526      * control is not found, moves focus to upper level container, if no

   527      * next focusable controls found in any of the upper level

   528      * containers, loops back to the first control.

   529      *

   530      * @since S60 ?S60_version

   531      * @return true, if focus was changed.

   532      */    

   533     OSN_IMPORT bool handleFocusNext();

   534     

   535     /**

   536      * handles focusing to previous control.

   537      * Handles also the container inside container cases. If next focusable

   538      * control is not found, moves focus to upper lever container, if no

   539      * previous focusable controls found in any of the upper level 

   540      * containers, loops back to the last control.

   541      *

   542      * @since S60 ?S60_version

   543      * @return true, if focus was changed.

   544      */        

   545     OSN_IMPORT bool handleFocusPrevious();

   546         

   547     /**

   548      * return the first focusable child control.

   549      * First focusable is also the default control to get the focus.

   550      *

   551      * @since S60 ?S60_version

   552      * @param aHostApi hostapi-instance. Use: for iterating the connected 

   553      *                 controls.

   554      * @return control, which should be the first to get the focus. 

   555      */        

   556     OSN_IMPORT virtual CAlfWidgetControl* getFirstFocusable(

   557                                               IAlfContainerWidget& aContainer);

   558 

   559     /**

   560      * return the last focusable child control.

   561      *

   562      * @since S60 ?S60_version

   563      * @param aHostApi hostapi-instance. Use: for iterating the connected

   564      *                 controls.

   565      * @return control, which should be the last one to get the focus

   566      */

   567     OSN_IMPORT virtual CAlfWidgetControl* getLastFocusable(

   568                                               IAlfContainerWidget& aContainer);

   569         

   570     /**

   571      * return next focusable control right after aControl

   572      *

   573      * @since S60 ?S60_version

   574      * @param aHostApi hostapi-instance. Use: for iterating the connected

   575      *                 controls.

   576      * @param aControl reference control

   577      * @return control, which should be focused right after aControl.

   578      *      If no focusable control left, should return 0.

   579      */

   580     OSN_IMPORT virtual CAlfWidgetControl* getFocusableAfter(

   581                                               IAlfContainerWidget& aContainer, 

   582                                               CAlfWidgetControl& aControl);

   583     

   584     /**

   585      * return next focusable control right before aControl.

   586      *

   587      * @since S60 ?S60_version

   588      * @param aHostApi hostapi-instance. Use: for iterating the connected

   589      *                 controls.

   590      * @param aControl reference control.

   591      * @return control, which should be focused right before aControl.

   592      *      If no focusable control left, should return 0.

   593      */

   594     OSN_IMPORT virtual CAlfWidgetControl* getFocusableBefore(

   595                                              IAlfContainerWidget& aContainer,

   596                                              CAlfWidgetControl& aControl);

   597 

   598     /**

   599      * Called when the control's focus state changes.

   600      */    

   601     OSN_IMPORT void FocusChanged(CAlfDisplay& aDisplay, TBool aFocused);

   602 

   603 private:

   604 

   605     // from base class MAlfEventHandler

   606 

   607     /**

   608      * Sends the event to processEvent method.

   609      * <b>Widgets are discouraged from overriding this method.</b>

   610      * Leaves with exception description if processEvent throws.

   611      * 

   612      * @since S60 ?S60_version

   613      * @param aEvent The event to be handled.

   614      * 

   615      * @return  <code>ETrue</code>, if the event was handled.

   616      *          Otherwise <code>EFalse</code>.

   617      *

   618      */

   619     OSN_IMPORT virtual TBool OfferEventL( const TAlfEvent& aEvent );

   620     

   621     /**

   622      * Calculate the child index inside a map.

   623      * In the data hierarchy, map items may by children

   624      * or containers of children. In order to calculate the

   625      * absolute child index, all previous map items need to be

   626      * considered. If the map is the root data, child items

   627      * with different element names are not considered.

   628      *

   629      * @since S60 ?S60_version

   630      * @param aMap              The map containing the children.

   631      * @param aMapIndex         The index inside the map.

   632      * @param aContainerIndex   The index inside the container.

   633      * @param aRoot             Is the map the root data.

   634      *

   635      * @return The child index.

   636      */

   637     uint childIndex( IAlfMap& aMap, uint aMapIndex, 

   638              uint aContainerIndex, bool aRoot );

   639                      

   640     /**

   641      * returns next control, that can be focused in relation to

   642      * the aControl.

   643      *

   644      * @since S60 ?S60_version

   645      * @param aControl reference control. 

   646      *

   647      * @return next focusable control, if aControl == 0, first focusable 

   648      *         control should be returned.

   649      */

   650     CAlfWidgetControl* nextFocusableControl(CAlfWidgetControl* aControl);

   651         

   652     /**

   653      * returns previous control, that can be focused in relation to

   654      * the aControl.

   655      *

   656      * @since S60 ?S60_version

   657      * @param aControl reference control, 

   658      *

   659      * @return previous focusable control, if aControl == 0, last focusable

   660      *         control should be returned.

   661      */

   662     CAlfWidgetControl* previousFocusableControl(CAlfWidgetControl* aControl);

   663         

   664     // Private state handler methods

   665 

   666     void enableStateVisible();

   667     void disableStateVisible();

   668     void enableStateEnabled();

   669     void disableStateEnabled();

   670     void enableStateFocused();

   671     void disableStateFocused();

   672     void enableStateFocusable();

   673     void disableStateFocusable();

   674 

   675     // Tools for checking state invariants

   676     static void checkStateInvariants(uint aNewState);

   677     void predictAndCheckStateInvariants(

   678              uint aChangePattern, bool aEnabling) const;

   679 

   680     /**

   681      * Removes presentaion elements that is associated with 

   682      * the eventhandler.This will remove the element reference from the 

   683      * element array .

   684      *

   685      * @since S60 ?S60_version

   686      * @param aEventHandler A reference to event handler associated with

   687      *                      presentation element.

   688      *

   689      * @return the pointer to element data holding the pointer to the element

   690      *         if it is found, else null

   691      */

   692     ElementData* removePesentationElementData(

   693                     IAlfWidgetEventHandler& aEventHandler );

   694 

   695     /**

   696      * Constants for aPhase parameter in function ProcessEventHandlingPhase.

   697      */

   698     static const int tunneling = 0;

   699     static const int bubbling = 1;

   700 

   701     /**

   702      * Goes through all the event handlers in either tunneling or 

   703      * bubbling phase.

   704      */

   705     AlfEventStatus ProcessEventHandlingPhase(

   706         int aPhase,

   707         const TAlfEvent& aEvent );

   708 

   709 private: // data

   710     auto_ptr<AlfWidgetControlImpl> mWdgtControlData;

   711     };

   712 

   713 #include "alf/alfwidgetcontrol.inl"

   714 

   715     } // namespace Alf

   716 

   717 #endif // ALFWIDGETCONTROL_H

   718