--- a/mmuifw_plat/alf_widgetmodel_api/inc/alf/ialfwidgetcontrol.h Tue Feb 02 00:28:09 2010 +0200
+++ /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 <osn/osntypes.h>
-#include <alf/ialfinterfacebase.h>
-#include <alf/alftypes.h>
-
-//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 <code>SetState( State() | aState )</code>.
- *
- * 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 <code>SetState( State() & ( 0xFFFFFFFF ^ aState ) )</code>.
- *
- * 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 <code>enabled = State() & aState</code>
- *
- * The parameter passed in should usually be a single bit state aspect
- * e.g. <code>IAlfWidgetControl::Focusable</code>
- * 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