/*

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

*

*/

#ifndef ALFWIDGETCONTROL_H

#define ALFWIDGETCONTROL_H

#include <osn/osndefines.h>

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

#include <alf/ialfwidgetcontrol.h>

#include <alf/alfcontrol.h>

#include <alf/ialfmodelchangeobserver.h>

#include <memory>

namespace osncore

    {

template <class T> class AlfPtrVector;

    }

namespace std

    {

template <class T> class auto_ptr;

    }

using namespace osncore;

using namespace std;

namespace Alf

    {

class IAlfContainerWidget;

class IAlfWidgetEventHandler;

class IAlfElement;

class AlfWidget;

class IAlfMap;

class IAlfVariantType;

class AlfWidgetControlImpl;

class IAlfHostAPI;

class IfId;

class ElementData;

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

 *  The base class for all widget controls.

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

 *  the Alfred environment or control groups. Controls are responsible

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

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

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

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

 *  of the widget logic.

 *

 *  @interfaces IAlfWidgetControl, IAlfHostAPI, IAlfAttributeOwner

 *  @lib alfwidgetmodel.lib

 *  @since S60 ?S60_version

 *  @status Draft

 */

class CAlfWidgetControl :

            public CAlfControl,

            public IAlfModelChangeObserver,

            public IAlfWidgetControl

    {

public:

    /**

     * The constructor.

     *

     * @since S60 ?S60_version

     * @param aEnv      The Alfred environment.

     */

    OSN_IMPORT CAlfWidgetControl(CAlfEnv& aEnv);

    /**

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

     * allocate memory.

     *

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

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

     * memory with zero.

     * 

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

     * which is typically:

     *

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

     * or

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

     * 

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

     *                memory for the object under construction.

     *

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

     *            This parameter is supplied automatically.

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

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

     *             Ownership transferred to caller.

     */

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

                                  throw (std::bad_alloc);

    /**

     * Destructor.

     */

    OSN_IMPORT virtual ~CAlfWidgetControl();

    /**

     * Set the owner widget of this control.

     * Called by AlfWidget::setControlL().

     *

     * @since S60 ?S60_version

     * @param aWidget The owner widget of this control.

     */

    void setOwnerWidget( AlfWidget* aWidget );

    /**

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

     * 

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

     */

    OSN_IMPORT CAlfLayout* ContainerLayout(

                   const CAlfControl* /*aConnected*/) const;

    /**

     * state.

     */

    OSN_IMPORT uint state() const;

    /**

     * sets the state.

     */

    OSN_IMPORT void setState( uint aState );

    /**

     * enables State.

     */

    OSN_IMPORT void enableState( uint aState );

    /**

     * disables State.

     */

    OSN_IMPORT void disableState( uint aState );

    /**

     * checks  State.

     */

    OSN_IMPORT bool checkState( uint aState ) const;

    /**

     * returns no of event handlers.

     */

    OSN_IMPORT int numEventHandlers() const;

    /**

     * returns the event handlers at the index.

     */

    OSN_IMPORT IAlfWidgetEventHandler& eventHandler( int aIndex );

    /**

     * returns event handler index.

     */

    OSN_IMPORT int eventHandlerIndex(

                   IAlfWidgetEventHandler& aEventHandler ) const;

    /**

     * returns finds the event handler .

     */

    OSN_IMPORT IAlfWidgetEventHandler* findEventHandler(

                   const TAlfEvent& aEvent );

    /**

     * adds an event handler.

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

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

     *     index but it fails.

     */

    OSN_IMPORT void addEventHandler(

                   IAlfWidgetEventHandler* aEventHandler,

                   int aIndex = -1 );

    /**

     * removes an event handlers.

     */

    OSN_IMPORT void removeAndDestroyEventHandler(

                   IAlfWidgetEventHandler& aEventHandler );

    /**

     * returns no of event handlers.

     */

    OSN_IMPORT void removeEventHandler(

                   IAlfWidgetEventHandler& aEventHandler );

    /**

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

     *

     * @since S60 ?S60_version

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

     *                   and destroyed.

     */

    OSN_IMPORT void removeAndDestroyEventHandler( const UString& aHandlerId );

    /**

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

     *

     * @since S60 ?S60_version

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

     *                   and destroyed.

     */

    OSN_IMPORT void removeAndDestroyEventHandler( UString& aHandlerId );

    /**

     * Remove and destroy all event handlers associated with presentation 

     * elements.

     * @since S60 ?S60_version

     */

    OSN_IMPORT void removeAndDestroyPresentationEventHandlers();

    /**

     * Removes all event handlers associated with presentation elements from 

     * this control.

     *

     * @since S60 ?S60_version

     */

    OSN_IMPORT void removePresentationEventHandlers();

    /**

     * Returns no of elements.

     */

    OSN_IMPORT int numElements() const;

    /**

     * Returns an element at the index.

     */

    OSN_IMPORT IAlfElement& element( int aIndex );

    /**

     * Finds an element with specified name.

     */

    OSN_IMPORT IAlfElement* findElement( const char* aName );

    /**

     * Adds an element in the end.

     * @exception std::bad_alloc

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

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

     *     in the widget control already.

     *

     * @param aElement Element to be added.

     * Ownership is transferred iff no exception is thrown.

     */

    OSN_IMPORT void addElement( IAlfElement* aElement );

    /**

     * removes and destroys an element.

     */

    OSN_IMPORT void removeAndDestroyElement( const IAlfElement& aElement );

   /**

     * removes an element but does not destroy it.

     */

    OSN_IMPORT void removeElement( const IAlfElement& aElement ); 

    /**

     * Returns the data id of an element.

     */

    OSN_IMPORT virtual uint elementDataId(

                           const IAlfElement& aElement,

                           uint aIndex,

                           uint aParentDataId );

    /**

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

     */

    OSN_IMPORT virtual uint parentElementDataId(

                           const IAlfElement& aElement,

                           uint aDataId );

    /**

     * Returns index corresponding to a data id.

     */

    OSN_IMPORT virtual uint dataIdToIndex(

                           const IAlfElement& aElement,

                           uint aDataId );

    /**

     * Returns data of an element.

     */

    OSN_IMPORT IAlfVariantType* elementData(

                   const IAlfElement& aElement,

                   uint aDataId );

    /**

     * Sets the data id range of an element.

     */

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

    /**

     * Returns the data id range of an element.

     */

    OSN_IMPORT uint dataIdRange( const IAlfElement& aElement );

    /**

     * Updates presentation.

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

     *    osncore::ECanNotCreateVisual when during updation of presentation, 

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

     *    visuals.

     * @since S60 ?S60_version

     */

    OSN_IMPORT void updatePresentation();

    /**

     * Destroys presentation (visual trees under elements).

     */

    OSN_IMPORT void destroyPresentation( int aTimeMilliseconds = 0 );

    /**

     * Destroys all visuals and elements.

     */

    OSN_IMPORT void destroyVisualsAndElements( int aTimeMilliseconds = 0 ); 

    /**

     * Return the owner widget of this control .

     */

    OSN_IMPORT AlfWidget* widget();

    /*

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

     * If there is no parent, nothing is done.

     */

    OSN_IMPORT void updateParentLayout();

    /*

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

     * 

     */

    OSN_IMPORT bool isContainer() const;

    /*

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

     */

    OSN_IMPORT bool isFocusable() const;

    /**

     * Template getter for interfaces provided by the control classes.

     * The type of the queried interface is specified by the

     * template parameter.

     *

     * @exception std::bad_alloc 

     *

     * @since S60 ?S60_version

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

     *

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

     *         supported or available.

     */

    template <class T>

    static T* makeInterface( CAlfWidgetControl* aControl );

    /**

     * Handles events sent to widget control.

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

     * The default implementation tunnels key events towards the 

     * focussed child widget. If custom events EEventFocusNextWidget/

     * EEventFocusPreviousWidget are received the default implementation

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

     * 

     * @since S60 ?S60_version

     * @param aEvent The event to be handled.

     *

     * @return Result of event processing. See AlfEventStatus.

     */

    OSN_IMPORT virtual AlfEventStatus handleEvent( const TAlfEvent& aEvent );

    /**

     * Processes the events sent to this control.

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

     * handleEvent method and the bubbling phase event handlers in 

     * that order till one of them consumes the event.

     *

     * @since S60 ?S60_version

     * @param aEvent The event to be handled.

     *

     * @return Result of event processing. See AlfEventStatus.

     */

    OSN_IMPORT AlfEventStatus processEvent( const TAlfEvent& aEvent );

// from base class IAlfModelChangeObserver

    /**

     * From IAlfInterfaceBase.

     * Update the control according to the changed model.

     * Destroy existing visuals and cancel all animation commands. 

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

     *

     * @since S60 ?S60_version

     * @param aModel The new model.

     */

    OSN_IMPORT virtual void modelChanged( IAlfModel& aModel );

    /**

     * Update the presentation according to the data changes.

     *

     * @since S60 ?S60_version

     * @param aArrayOfOperation An Array containing the operations performed 

     *                          on the model.

     */

    OSN_IMPORT virtual void dataChanging(

                          const AlfPtrVector<AlfModelOperation>& aOperations );

    /**

     * Update the presentation according to the data changes.

     *

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

     *     osncore::ECanNotCreateVisual when adding the visual tree through

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

     *     is failed.

     *

     * @since S60 ?S60_version

     * @param aOperation An operation performed on the model.

     */

    OSN_IMPORT virtual void dataChanging(

                           const AlfModelOperation& aOperation );

    /**

     * The default implementation is empty.

     * Derived classes may update the state of the

     * control according to the changed data.

     *

     * @since S60 ?S60_version

     */

    OSN_IMPORT virtual void dataChanged();

// from base class IAlfInterfaceBase

    /**

     * From IAlfInterfaceBase.

     * Getter for interfaces provided by the control classes.

     * Derived classes should always call the base class method

     * from the overridden MakeInterface.

     *

     * @since S60 ?S60_version

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

     *

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

     *         supported or available.

     */

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

public:

// New non-virtual methods

    /**

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

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

     * and appended to the given control group.

     *

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

     */

    void resetControlGroup(CAlfControlGroup& aControlGroup);

    /**

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

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

     * connections.

     *

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

     * their previous control groups.

     *

     * @since S60 ?S60_version

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

     *        This control group replaces control groups to which the controls

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

     */

    void resetHierarchyControlGroup(CAlfControlGroup& aControlGroup);

    /**

     * Attempt to acquire focus for this control.

     */

    OSN_IMPORT void AcquireFocus();

    /**

     * Attempt to relinquish focus for this control.

     */ 

    OSN_IMPORT void RelinquishFocus();

    /**

     * returns hostApi for this control.

     * 

     * @return hostApi-instance.

     */

    IAlfHostAPI& hostAPI();

protected:

    /**

     * The protected constructor.

     *

     * @since S60 ?S60_version

     */

    OSN_IMPORT CAlfWidgetControl();

    /**

     * The constructor.

     *

     * @since S60 ?S60_version

     * @param aEnv The Alfred environment.

     */

    OSN_IMPORT void construct(CAlfEnv& aEnv);

    /**

     * handles focusing to next control. 

     * Handles the container inside container cases. If next focusable

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

     * next focusable controls found in any of the upper level

     * containers, loops back to the first control.