--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/mmuifw_plat/alf_widgetmodel_api/inc/alf/alfwidgetcontrol.h Thu Dec 17 08:56:02 2009 +0200
@@ -0,0 +1,718 @@
+/*
+* 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 <osn/osndefines.h>
+#include <osn/osnnew.h> // for OSN operator new parameter types
+#include <alf/ialfwidgetcontrol.h>
+#include <alf/alfcontrol.h>
+#include <alf/ialfmodelchangeobserver.h>
+#include <memory>
+namespace osncore
+ {
+template <class T> class AlfPtrVector;
+ }
+
+namespace std
+ {
+template <class T> 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<CAlfWidgetControl> 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 <class T>
+ static T* makeInterface( CAlfWidgetControl* aControl );
+
+ /**
+ * Handles events sent to widget control.
+ * <b> Widgets can override this. </b>
+ * 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<AlfModelOperation>& 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.
+ * <b>Widgets are discouraged from overriding this method.</b>
+ * Leaves with exception description if processEvent throws.
+ *
+ * @since S60 ?S60_version
+ * @param aEvent The event to be handled.
+ *
+ * @return <code>ETrue</code>, if the event was handled.
+ * Otherwise <code>EFalse</code>.
+ *
+ */
+ 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<AlfWidgetControlImpl> mWdgtControlData;
+ };
+
+#include "alf/alfwidgetcontrol.inl"
+
+ } // namespace Alf
+
+#endif // ALFWIDGETCONTROL_H
+