diff -r 4ea6f81c838a -r 0e9bb658ef58 inc/alf/alfwidget.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/inc/alf/alfwidget.h Wed Sep 01 12:23:18 2010 +0100 @@ -0,0 +1,332 @@ +/* +* 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 ALFWIDGET_H +#define ALFWIDGET_H + +#include +#include +#include +#include +#include "alf/ialfcontainerwidget.h" +#include + +#include + + +class CAlfEnv; +class CAlfDisplay; + +namespace osncore + { +template class AlfPtrVector; + } + +using namespace std; +using namespace osncore; + + +namespace Alf + { + +//class CAlfWidgetControl; +class IAlfModel; +class IAlfWidgetFactory; +class AlfWidgetImpl; + + +/** + * @class AlfWidget alfwidget.h "alf/alfwidget.h" + * The base class for widgets. + * @see IAlfWidget IAlfContainerWidget IAlfHostApi + * + * @lib alfwidgetmodel.lib + * @since S60 ?S60_version + * @status Draft + * @interfaces IAlfWidget,IAlfAttributeOwner,IAlfContainerWidget,IAlfWidgetControl,IAlfHostAPI, + * All interfaces returned by the elements associated with the widget's control, + * All interfaces returned by the layout manager associated widget control , + * All interfaces returned by the model assoiated with the widget. + */ +class AlfWidget : public IAlfContainerWidget + { +public: + /** + * Constructor. + * + * This will create a default control to the widget to enable the widget + * containment hierarchy from the beginning. User can replace the default + * control with custom control by calling the setControl() - method. + * @exception std::bad_alloc + * + * @see setControl() + * + * @param aWidgetName The name of the widget. + * @param aContainer Container widget that will contain this widget. + * @param aEnv Toolkit environment object that will be used to create the + * default control. + */ + OSN_IMPORT AlfWidget(const char* aWidgetName, IAlfContainerWidget& aContainer, CAlfEnv& aEnv); + + /** + * Constructor to be used only by view widget. + * All the other widgets should use the other public constructor to ensure + * widget hierarchy consistency from start. + * @exception std::bad_alloc + * + * @see AlfWidget(const char*, IAlfContainerWidget&, CAlfEnv&) + * + * @param aWidgetName The name of the widget. + */ + OSN_IMPORT AlfWidget(const char* aWidgetName); + + /** + * Destructor. + * + * It also takes care that all the child widgets contained by this widget + * are destroyed correctly, provided that they have been instantiated correctly + * (e.g. through widget factory) and thus added to the ALF environment (CAlfEnv). + * + * In other words, client code does not need to take care of destroying the child + * widgets contained by a container widget. + */ + OSN_IMPORT virtual ~AlfWidget(); + + /** + * Constructor. The new widget is left on the cleanup stack. + * + * @since S60 ?S60_version + * @param aWidgetName The name of the widget. + * @return New object. The widgets are owned by Alfred. + */ + OSN_IMPORT CAlfWidgetControl* control() const; + + /** + * Getter for the parent container. The ownership is not passed. + * + * @return the parent container or 0 if the widget is the root-widget. + */ + OSN_IMPORT IAlfContainerWidget* parent() const; + + /** + * Sets new widget control to this widget. + * @exception osncore::AlfException Thrown with error code osncore::EInvalidArgument if aControl is + * alreasy associated with another widget. + * @see IAlfWidget::setControl() + * + * @since S60 ?S60_version + * @param aControl Control to be set to the widget. + * @param aDeletePreviousControl If true, the previous widget control is destroyed. + */ + OSN_IMPORT void setControl(CAlfWidgetControl* aControl, bool aDeletePreviousControl = true); + + /** + * Constructor. The new widget is left on the cleanup stack. + * + * @since S60 ?S60_version + * @param aWidgetName The name of the widget. + * @return New object. The widgets are owned by Alfred. + */ + OSN_IMPORT IAlfModel* model(); + + /** + * Sets the model for the Widget. + * + * @since S60 ?S60_version + * @param aModel Model to be set to this widget. + * @param aTakeOwnership Whether takes ownership or not. + */ + OSN_IMPORT void setModel( IAlfModel* aModel,bool aTakeOwnerShip=true ); + + /** + * Constructor. The new widget is left on the cleanup stack. + * + * @since S60 ?S60_version + * @param aWidgetName The name of the widget. + * @return New object. The widgets are owned by Alfred. + */ + OSN_IMPORT const char* widgetName() const; + + //From IAlfInterfaceBase + /** + * Getter for interfaces provided by the widget, the control, + * or the model. + * + * @since S60 ?S60_version + * @param aWidget The widget to get the interface for. + * @param aType The type id of the queried interface. + * @return The queried interface, or NULL if the interface is not + * supported or available. + */ + OSN_IMPORT static IAlfInterfaceBase* makeInterface( AlfWidget* aWidget, const IfId& aType ); + + /** + * Template getter for interfaces provided by the widget, the control, + * or the model. The type of the queried interface is specified by the + * template parameter. + * + * @since S60 ?S60_version + * @param aWidget The widget to get the interface for. + * @return The queried interface, or NULL if the interface is not + * supported or available. + */ + template + static T* makeInterface( AlfWidget* aWidget ); + + // from base class IAlfInterfaceBase + + /** + * From IAlfInterfaceBase. + * Getter for interfaces provided by the widget 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 ); + + // from base class IAlfContainerWidget + + /** + * Returns total number of widgets contained by this container. + * + * @return int Total number of widgets. + */ + OSN_IMPORT int widgetCount() const; + + /** + * Adds a child widget to the container. + * + * @param aWidget Child widget to be added to container. + * return void + */ + OSN_IMPORT void addWidget(IAlfWidget& aWidget); + + /** + * Returns child widget at given index.If index is not found return null. + * + * @param aIndex Index of widget to be returned. + * @return Widget at given index + */ + OSN_IMPORT IAlfWidget* getWidget(int aIndex) const; + + /** + * Returns the child index, when given the child widget. + * + * @param aWidget child widget, which index is returned + * @return the index of the child widget, or -1, if widget is not child of this container. + */ + OSN_IMPORT int getWidgetIndex(IAlfWidget& aWidget) const; + + /** + * Removes the child widget from given index. + * + * @param aIndex Index from which widget has to be removed. + * return void + */ + void removeWidget(int aIndex); + + /** + * Sets the base layout of container widget. + * + * @param aLayout New base layout of container widget. + * return void + */ + OSN_IMPORT void applyLayout(IAlfLayoutManager& aLayout); + + //from IAlfWidget + + /** + * Sets/Releases the Focus from child widget of container. + * Does not set the actual focused status in roster. + * + * @since S60 ?S60_version + * @param aFocus boolean value for focused status + * return void + */ + OSN_IMPORT void setChildFocus(bool aFocus); + + /** + * Removes the given widget from this widget's child widget + * array. Does not modify control connections or control + * group containment. + * + * Does nothing if the given widget is not found from + * widget array. + * + * @param aWidget Reference to a widget that is searched + * from the widget array of this widget and removed + * of found. + */ + OSN_IMPORT void removeWidget(IAlfWidget& aWidget); + + /** + * Sets the presentation for the widget using presentation XML file. + * Destroys any existing presentation. + * @param aFilePath Path to XML file describing the presentation + * of the widget. Not Owned. + * @exception AlfWidgetException if no visualization node available + * in Presentation XML or if no control + * is associated with the widget. + * @exception bad_alloc + * @since S60 ?S60_version + * @return void. + */ + OSN_IMPORT void setPresentation(const char* aFilePath); + +protected: + + /** + * The protected constructor. + * + * @since S60 ?S60_version + */ + OSN_IMPORT AlfWidget(); + +private: + + /** + * Adds the Common Properties for the widget + * + * @since S60 ?S60_version + */ + void addCommonWidgetProperties(); + + /** + * Removes reference from this widget's control to this + * widget. + */ + void removeReferenceFromControl(); + +private: // data + + auto_ptr mImpl; + }; + +using namespace osncore; + +#include "alf/alfwidget.inl" + + } // namespace Alf + +#endif // ALFWIDGET_H + +// End of File