diff -r 514d98f21c43 -r 4ea6f81c838a mmuifw_plat/alf_widgetmodel_api/inc/alf/ialfwidgetcontrol.h --- a/mmuifw_plat/alf_widgetmodel_api/inc/alf/ialfwidgetcontrol.h Mon Jun 21 16:15:51 2010 +0300 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,506 +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 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