--- /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 <osn/osndefines.h>
+#include <alf/ialfwidget.h>
+#include <memory>
+#include <osn/ustring.h>
+#include "alf/ialfcontainerwidget.h"
+#include <alf/alfwidgetcontrol.h>
+
+#include <vector>
+
+
+class CAlfEnv;
+class CAlfDisplay;
+
+namespace osncore
+ {
+template <class T> 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 <class T>
+ 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<AlfWidgetImpl> mImpl;
+ };
+
+using namespace osncore;
+
+#include "alf/alfwidget.inl"
+
+ } // namespace Alf
+
+#endif // ALFWIDGET_H
+
+// End of File