diff -r 4ea6f81c838a -r 0e9bb658ef58 mmuifw_plat/alf_widgetmodel_api/inc/alf/ialfwidgetcontrol.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mmuifw_plat/alf_widgetmodel_api/inc/alf/ialfwidgetcontrol.h Wed Sep 01 12:23:18 2010 +0100 @@ -0,0 +1,506 @@ +/* +* 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 widgets. +* +*/ + + +#ifndef I_ALFWIDGETCONTROL_H +#define I_ALFWIDGETCONTROL_H + +#include +#include +#include + +//FORWARD DECLARATION +class TAlfEvent; +class CAlfDisplay; + +namespace osncore + { + class UString; + } +using namespace osncore; + +namespace Alf + { +//FORWARD DECLARATIONS +class IAlfWidgetEventHandler; +class IAlfElement; +class AlfWidget; +class IAlfVariantType; +class AlfCustomInitDataBase; + + +namespace alfwidgetcontrol + { +static const IfId ident= + { + 0,"alfwidgetcontrol" + }; + } + +/** + * The interface for widget controls. + * Widget controls are derived from Alfred controls. This is + * the primary interface to access the widget control functionality. + * Alfred control interface can be queried, but direct access should not + * be needed. Widget 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. + * + * @lib alfwidgetmodel.lib + * @since S60 ?S60_version + * @status Draft + */ +class IAlfWidgetControl : public IAlfInterfaceBase + { +public: + + /** + * Defines the bitflags used with the state interfaces. + */ + + // Visible is set if the widget control is currently intended to be visible + static const uint Visible = 0x0001; + + // Enabled is set if the widget control is to be responsive to user input + // Note: Presentation may render this control in some way to indicate that + // it is disabled + static const uint Enabled = 0x0002; + + // Focused is set if the control is to be currently attracting key events + static const uint Focused = 0x0004; + + // Focusable is set iff the widget control is to allow focus to be put + // on it + static const uint Focusable = 0x0008; + +public: + static inline const IfId& type() + { + return alfwidgetcontrol::ident; + } + /** + * Virtual destructor. + * + * @since S60 ?S60_version + */ + virtual ~IAlfWidgetControl() {} + + /** + * Get the state of the control. + * The state is a combination of binary state flags. + * + * The individual aspects of the state can be queried by testing + * for the bits in the return value. + * + * @since S60 ?S60_version + * @return The bit-pattern encoding the state + */ + virtual uint state() const = 0; + + /** + * Sets the widget control's state. + * + * The entire state of the widget is set to the passed-in value. + * + * The new state must conform to the following invariants: + * + * If IAlfWidgetControl::Focus is set, then IAlfWidgetControl::Focusable must also be set + * If IAlfWidgetControl::Focusable is set, then IAlfWidgetControl::Enabled must also be set + * + * If these invariants are violated, then this method will throw AlfException::EInvalidArgument + * + * @since S60 ?S60_version + * @param aState The new state of the control. + */ + virtual void setState( uint aState ) = 0; + + /** + * Enable given states. + * + * This method modifies a state by enabling bits. No bits are disabled. + * This is equal to SetState( State() | aState ). + * + * The resulting state is tested for the invariants documented with setState() + * and throws the same exceptions. + * + * @since S60 ?S60_version + * @param aState The states to be enabled. + */ + virtual void enableState( uint aState ) = 0; + + /** + * Disable given states. + * + * This method modifies a state by clearing bits. No bits are set. + * This is equal to SetState( State() & ( 0xFFFFFFFF ^ aState ) ). + * + * The resulting state is tested for the invariants documented with setState() + * and throws the same exceptions. + * + * @since S60 ?S60_version + * @param aState The states to be disabled. + */ + virtual void disableState( uint aState ) = 0; + + /** + * Checks the current state of the widget control for a single aspect. + * This is equal to enabled = State() & aState + * + * The parameter passed in should usually be a single bit state aspect + * e.g. IAlfWidgetControl::Focusable + * If a pattern with more than one bit set is passed in, the result + * is not easily usable. + * + * @since S60 ?S60_version + * @param aState a state bit pattern to test + * @return true if and only one of the passed-in bits is set in the state + */ + virtual bool checkState( uint aState ) const = 0; + + /** + * Get the number of event handlers in the control. + * + * @since S60 ?S60_version + * @return The number of event handlers. + */ + virtual int numEventHandlers() const = 0; + + /** + * Get an event handler by index. + * + * @since S60 ?S60_version + * @param aIndex The index of the event handler to get. + * + * @return The event handler at the given index. + */ + virtual IAlfWidgetEventHandler& eventHandler( int aIndex ) = 0; + + /** + * Get the index of the given event handler. + * The index specifies the order in which + * the event handlers are processed. + * + * @since S60 ?S60_version + * @param aEventHandler The event handler. + * + * @return The index of the event handler, or -1 if the event handler + * does not exist. + */ + virtual int eventHandlerIndex( + IAlfWidgetEventHandler& aEventHandler ) const = 0; + + + /** + * Find an event handler responsible for the given event. + * + * @since S60 ?S60_version + * @param aEvent The event. + * + * @return The first event handler to handle the given event, or NULL + * if not found. + */ + virtual IAlfWidgetEventHandler* findEventHandler( + const TAlfEvent& aEvent ) = 0; + + /** + * Add a new event handler. + * The control takes the ownership of the event handler. + * + * @since S60 ?S60_version + * @param aEventHandler The event handler to be added. + * @param aIndex The index of the new event handler, + * or -1 to append the event handler after the existing + * event handlers. + */ + virtual void addEventHandler( + IAlfWidgetEventHandler* aEventHandler, + int aIndex = -1 ) = 0; + + /** + * Remove and destroy an event handler. + * + * @since S60 ?S60_version + * @param aEventHandler The event handler to be removed and destroyed. + */ + virtual void removeAndDestroyEventHandler( + IAlfWidgetEventHandler& aEventHandler ) = 0; + + /** + * 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. + */ + virtual void removeAndDestroyEventHandler( const UString& aHandlerId ) = 0; + + + /** + * Remove and destroy an event handler. + * + * @since S60 ?S60_version + * @param aEventHandler The event handler to be removed and destroyed. + */ + virtual void removeEventHandler( + IAlfWidgetEventHandler& aEventHandler ) = 0; + + + /** + * Remove and destroy all event handlers associated with presentation. + * + * @since S60 ?S60_version + */ + virtual void removeAndDestroyPresentationEventHandlers() = 0; + + /** + * Removes all event handlers associated with presentation from + * this control. + * + * @since S60 ?S60_version + */ + virtual void removePresentationEventHandlers() = 0; + + /** + * Get the number of elements in the control. + * + * @since S60 ?S60_version + * @return The number of elements. + */ + virtual int numElements() const = 0; + + /** + * Get an element by index. + * + * @since S60 ?S60_version + * @param aIndex The index of the element to get. + * + * @return The element at the given index. + */ + virtual IAlfElement& element( int aIndex ) = 0; + + /** + * Find an element by name. + * + * @since S60 ?S60_version + * @param aName The name of the element to find. + * + * @return The found element, or NULL if not found. + */ + virtual IAlfElement* findElement( const char* aName ) = 0; + + /** + * Add a new element. + * The control takes the ownership of the element. + * + * @since S60 ?S60_version + * @param aElement The element to be added. + */ + virtual void addElement( IAlfElement* aElement ) = 0; + + /** + * Remove and destroy an element. All visuals created by the + * element are destroyed. + * + * @since S60 ?S60_version + * @param aElement The element to be removed and destroyed. + */ + virtual void removeAndDestroyElement( const IAlfElement& aElement ) = 0; + + /** + * Remove an element. + * + * @since S60 ?S60_version + * @param aElement The element to be removed. + */ + virtual void removeElement( const IAlfElement& aElement ) = 0; + + /** + * Get an id for mapping data to a visual tree created by an element. + * The data id is required to be unique withing the scope of the element. + * The parent data id and data id ranges specified by SetDataIdRange can + * be used to calculate data ids in hierarchical element structures. + * In the default implementation, the data id is calculated as follows: + * \f[ + * data id = aParentDataId * DataIdRange( aElement ) + aIndex + * \f] + * + * @since S60 ?S60_version + * @param aElement The element to associate the data id with. + * @param aIndex The index of the data field. + * @param aParentDataId The parent data id in the data hierarchy. + * @return A unique data id for mapping data to a visual tree. + */ + virtual uint elementDataId( + const IAlfElement& aElement, + uint aIndex, + uint aParentDataId ) = 0; + + /** + * Get the parent data id from the given data id. + * In the default implementation, the parent data id is calculated + * as follows: + * \f[ + * parent data id = aDataId / DataIdRange( aElement ) + * \f] + * The implementation should match the functionality of ElementDataId(). + * + * @since S60 ?S60_version + * @param aElement The element associated with the given data id. + * @param aDataId The data id. + * @return The parent data id. + */ + virtual uint parentElementDataId( + const IAlfElement& aElement, + uint aDataId ) = 0; + + /** + * Get the index of the given child data id in the parent data container. + * In the default implementation, the parent data id is calculated + * as follows: + * \f[ + * index = aDataId % DataIdRange( aElement ) + * \f] + * The implementation should match the functionality of ElementDataId(). + * + * @since S60 ?S60_version + * @param aElement The element associated with the given data id. + * @param aDataId The data id. + * @return The parent data id. + */ + virtual uint dataIdToIndex( + const IAlfElement& aElement, + uint aDataId ) = 0; + + /** + * Get data for a visual tree created by the given element. + * + * @since S60 ?S60_version + * @param aElement The element containing the visual tree. + * @param aDataId The data id of the visual tree. + * @return Data for the visual tree. + */ + virtual IAlfVariantType* elementData( + const IAlfElement& aElement, + uint aDataId ) = 0; + + /** + * Set the range of data ids for an element. + * The range is used for data mapping in ElementDataId() and ElementData(). + * The default range for all elements is 0xFFFFFFFF. The ranges need to be + * adjusted for child elements in hierarchical element structures. + * Otherwise,the data ids will overflow and not remain unique. + * @see ElementDataId(). + * + * @since S60 ?S60_version + * @param aElement The element. + * @param aRange The range of data ids. + */ + virtual void setDataIdRange( + const IAlfElement& aElement, + uint aRange ) = 0; + + /** + * Get the range of data ids for the given element. + * The range is used for data mapping in ElementDataId() and ElementData(). + * @see SetDataIdRange(). + * + * @since S60 ?S60_version + * @param aElement The element. + * @return The range of data ids for the element. + */ + virtual uint dataIdRange( const IAlfElement& aElement ) = 0; + + /** + * Create or update the presentation for the widget. + * + * @since S60 ?S60_version + */ + virtual void updatePresentation() = 0; + + /** + * Remove visuals from all elements. The visuals are destroyed + * after the given delay. This allows executing an animation + * sequence before the actual destruction of visuals. + * + * @since S60 ?S60_version + * @param aTimeMilliseconds The remaining time to destruction of + * all visuals. + */ + virtual void destroyPresentation( int aTimeMilliseconds ) = 0; + + /** + * Remove visuals from all elements and destroy all elements. + * The visuals and elements are destroyed after the given delay. + * This allows executing an animation sequence before the actual + * destruction of visuals. + * + * @since S60 ?S60_version + * @param aTimeMilliseconds The remaining time to destruction of + * all visuals. + */ + virtual void destroyVisualsAndElements( int aTimeMilliseconds = 0 ) = 0; + + /** + * Get the owner widget of this control. + * + * @since S60 ?S60_version + * @return The owner widget, or NULL if this control does not belong to + * any widget. + */ + virtual AlfWidget* widget() = 0; + + /** + * Handles events sent to widget control. + * + * @since S60 ?S60_version + * @param aEvent The event to be handled. + * @return Result of event processing. See AlfEventStatus. + */ + virtual AlfEventStatus handleEvent( const TAlfEvent& aEvent ) = 0; + + }; + +/** + * Placeholder for information required to instantiate a widgetcontrol + * via the widget factory mechanism. + * A pointer to this structure is casted to a void pointer and sent to the + * factory plugin. + * @lib alfwidgetmodel.lib + * @since S60 ?S60_version + */ +struct AlfWidgetControlInitData + { + + /** + * Display pointer + */ + CAlfDisplay* mDisplay; + + /** + * Pointer to custom data passed via factory mechanism + * Not Owned. + */ + AlfCustomInitDataBase* mCustomData; + }; + + } // namespace Alf + +#endif // I_ALFWIDGETCONTROL_H + +// End of File