/*
* 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