diff -r 4526337fb576 -r 3eca7e70b1b8 mmuifw_plat/alf_widgetmodel_api/inc/alf/alfwidgetcontrol.h --- a/mmuifw_plat/alf_widgetmodel_api/inc/alf/alfwidgetcontrol.h Tue Feb 02 00:28:09 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,718 +0,0 @@ -/* -* 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 -#include // for OSN operator new parameter types -#include -#include -#include -#include -namespace osncore - { -template class AlfPtrVector; - } - -namespace std - { -template 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 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 - static T* makeInterface( CAlfWidgetControl* aControl ); - - /** - * Handles events sent to widget control. - * Widgets can override this. - * 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& 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. - * - * @since S60 ?S60_version - * @return true, if focus was changed. - */ - OSN_IMPORT bool handleFocusNext(); - - /** - * handles focusing to previous control. - * Handles also the container inside container cases. If next focusable - * control is not found, moves focus to upper lever container, if no - * previous focusable controls found in any of the upper level - * containers, loops back to the last control. - * - * @since S60 ?S60_version - * @return true, if focus was changed. - */ - OSN_IMPORT bool handleFocusPrevious(); - - /** - * return the first focusable child control. - * First focusable is also the default control to get the focus. - * - * @since S60 ?S60_version - * @param aHostApi hostapi-instance. Use: for iterating the connected - * controls. - * @return control, which should be the first to get the focus. - */ - OSN_IMPORT virtual CAlfWidgetControl* getFirstFocusable( - IAlfContainerWidget& aContainer); - - /** - * return the last focusable child control. - * - * @since S60 ?S60_version - * @param aHostApi hostapi-instance. Use: for iterating the connected - * controls. - * @return control, which should be the last one to get the focus - */ - OSN_IMPORT virtual CAlfWidgetControl* getLastFocusable( - IAlfContainerWidget& aContainer); - - /** - * return next focusable control right after aControl - * - * @since S60 ?S60_version - * @param aHostApi hostapi-instance. Use: for iterating the connected - * controls. - * @param aControl reference control - * @return control, which should be focused right after aControl. - * If no focusable control left, should return 0. - */ - OSN_IMPORT virtual CAlfWidgetControl* getFocusableAfter( - IAlfContainerWidget& aContainer, - CAlfWidgetControl& aControl); - - /** - * return next focusable control right before aControl. - * - * @since S60 ?S60_version - * @param aHostApi hostapi-instance. Use: for iterating the connected - * controls. - * @param aControl reference control. - * @return control, which should be focused right before aControl. - * If no focusable control left, should return 0. - */ - OSN_IMPORT virtual CAlfWidgetControl* getFocusableBefore( - IAlfContainerWidget& aContainer, - CAlfWidgetControl& aControl); - - /** - * Called when the control's focus state changes. - */ - OSN_IMPORT void FocusChanged(CAlfDisplay& aDisplay, TBool aFocused); - -private: - - // from base class MAlfEventHandler - - /** - * Sends the event to processEvent method. - * Widgets are discouraged from overriding this method. - * Leaves with exception description if processEvent throws. - * - * @since S60 ?S60_version - * @param aEvent The event to be handled. - * - * @return ETrue, if the event was handled. - * Otherwise EFalse. - * - */ - OSN_IMPORT virtual TBool OfferEventL( const TAlfEvent& aEvent ); - - /** - * Calculate the child index inside a map. - * In the data hierarchy, map items may by children - * or containers of children. In order to calculate the - * absolute child index, all previous map items need to be - * considered. If the map is the root data, child items - * with different element names are not considered. - * - * @since S60 ?S60_version - * @param aMap The map containing the children. - * @param aMapIndex The index inside the map. - * @param aContainerIndex The index inside the container. - * @param aRoot Is the map the root data. - * - * @return The child index. - */ - uint childIndex( IAlfMap& aMap, uint aMapIndex, - uint aContainerIndex, bool aRoot ); - - /** - * returns next control, that can be focused in relation to - * the aControl. - * - * @since S60 ?S60_version - * @param aControl reference control. - * - * @return next focusable control, if aControl == 0, first focusable - * control should be returned. - */ - CAlfWidgetControl* nextFocusableControl(CAlfWidgetControl* aControl); - - /** - * returns previous control, that can be focused in relation to - * the aControl. - * - * @since S60 ?S60_version - * @param aControl reference control, - * - * @return previous focusable control, if aControl == 0, last focusable - * control should be returned. - */ - CAlfWidgetControl* previousFocusableControl(CAlfWidgetControl* aControl); - - // Private state handler methods - - void enableStateVisible(); - void disableStateVisible(); - void enableStateEnabled(); - void disableStateEnabled(); - void enableStateFocused(); - void disableStateFocused(); - void enableStateFocusable(); - void disableStateFocusable(); - - // Tools for checking state invariants - static void checkStateInvariants(uint aNewState); - void predictAndCheckStateInvariants( - uint aChangePattern, bool aEnabling) const; - - /** - * Removes presentaion elements that is associated with - * the eventhandler.This will remove the element reference from the - * element array . - * - * @since S60 ?S60_version - * @param aEventHandler A reference to event handler associated with - * presentation element. - * - * @return the pointer to element data holding the pointer to the element - * if it is found, else null - */ - ElementData* removePesentationElementData( - IAlfWidgetEventHandler& aEventHandler ); - - /** - * Constants for aPhase parameter in function ProcessEventHandlingPhase. - */ - static const int tunneling = 0; - static const int bubbling = 1; - - /** - * Goes through all the event handlers in either tunneling or - * bubbling phase. - */ - AlfEventStatus ProcessEventHandlingPhase( - int aPhase, - const TAlfEvent& aEvent ); - -private: // data - auto_ptr mWdgtControlData; - }; - -#include "alf/alfwidgetcontrol.inl" - - } // namespace Alf - -#endif // ALFWIDGETCONTROL_H -