diff -r 4ea6f81c838a -r 0e9bb658ef58 mmuifw_plat/alf_widgetmodel_api/inc/alf/ialfwidget.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mmuifw_plat/alf_widgetmodel_api/inc/alf/ialfwidget.h Wed Sep 01 12:23:18 2010 +0100 @@ -0,0 +1,234 @@ +/* +* 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_ALFWIDGET_H +#define I_ALFWIDGET_H + + +#include +#include +#include + +namespace duiuimodel + { +class DuiNode; + } + +using namespace duiuimodel; + +class CAlfEnv; + +namespace Alf + { + +class CAlfWidgetControl; +class IAlfModel; +class IAlfWidgetFactory; +class IAlfContainerWidget; +class AlfCustomInitDataBase; + + +namespace alfwidget + { +static const IfId ident= + { + 0,"alfwidget" + }; + } +/** + * An interface for all widgets. + * Widgets consist of a model and a control. + * The model is owned by the widget, but all + * controls are owned by Alfred environment. + * The widget can be queried for interfaces provided + * by derived widget classes, the control or the model. + * Widgets can be constructed using the widget factory. + * Widgets are owned and accessed using the Alfred + * environment. + * + * @lib alfwidgetmodel.lib + * @since S60 ?S60_version + * @status Draft + */ +class IAlfWidget : public IAlfInterfaceBase + { +public: + static inline const IfId& type() + { + return alfwidget::ident; + } + + /** Virtual destructor. */ + virtual ~IAlfWidget() {} + + /** + * Getter for the control. The ownership is not passed. + * + * @since S60 ?S60_version + * @return The control of this widget, or NULL if the control is not specified. + */ + virtual CAlfWidgetControl* control() const = 0; + + /** + * Getter for the parent container. The ownership is not passed. + * + * @return the parent container or 0 if the widget is the root-widget. + */ + virtual IAlfContainerWidget* parent() const = 0; + + /** + * Sets a new widget control. After this call has been succesfully executed, the control is + * owned by this widget. When a new widget control is set to a widget the previously set widget + * control is removed. + * + * Through the aDeletePreviousControl - parameter user can specify whether the previously set + * control is destroyed when new control is set. Otherwise the previous control is left on the + * ownership of the caller. The caller has to manually delete the control or reset it to another + * widget or control group. + * + * If the control passed through this method exists in a control group it is appended to the + * control group of the view where this widget is contained in and removed from its previous + * control group. + * + * Widget should always have a valid control. An osncore::AlfException is thrown with error code + * osncore::EInvalidArgument if a control that is already used in another widget is attempted to + * be used with this widget. You have to replace the control in the source widget first + * before you can reuse that control in the target widget. See two code snippets below for details: + * + * @code + * // This will throw an osncore::AlfException with error code osncore::EInvalidArgument. + * targetWidget.setControl(sourceWidget.control()); + * @endcode + * + * @code + * CAlfWidgetControl* control = sourceWidget.control(); + * sourceWidget.setControl(newControl, false); + * // This is ok, since control is not set in sourceWidget anymore. + * targetWidget.setControl(control); + * @endcode + * + * @see IAlfViewWidget + * + * @param aControl The new widget control to be used with this widget. + * @param aDeletePreviousControl If set to true will destroy the previously set control from UI Accelerator Toolkit Environment. + * + * @exception osncore::AlfException If the given control is already set to another widget an osncore::AlfException + * is thrown with error code osncore::EInvalidArgument. + */ + virtual void setControl( CAlfWidgetControl* aControl, bool aDeletePreviousControl = true ) = 0; + + /** + * Getter for the model. The ownership is not passed. + * + * @since S60 ?S60_version + * @return The model of this widget, or NULL if the model is not specified. + */ + virtual IAlfModel* model() = 0; + + /** + * Setter for the model. Ownership is passed and the old model is released. + * + * @since S60 ?S60_version + * @param aModel The model for this widget. + * @param aTakeOwnership Whether takes ownership of model or not + * return void + */ + virtual void setModel( IAlfModel* aModel,bool aTakeOwnership = true) = 0; + + /** + * Get the name of the widget instance. + * + * @since S60 ?S60_version + * @return Widget name + */ + virtual const char* widgetName() const = 0; + + /** + * 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 + */ + virtual void setChildFocus(bool aFocus) = 0; + + /** + * 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. + */ + virtual void setPresentation(const char* aFilePath) = 0; + }; + +/** + * Placeholder for information required to instantiate a widget + * 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 AlfWidgetInitData + { + /** + * Owner environment for the widget + */ + CAlfEnv* mEnv; + + /** + * Container widget pointer that is going to contain the created widget. + */ + IAlfContainerWidget* mContainerWidget; + + /** + * Widget instance ID.This uniquely identifies every widget instance + * and is its name. Also see AlfWidget::Widgetname(). + */ + char* mWidgetId; + + /** + * Pointer to node in declaration containing information for the widget. + */ + DuiNode* mNode; + + /** + * XML file name containing the declaration for the presention of the widget. + */ + const char* mFilePath; + + /** + * Pointer to custom data passed via factory mechanism + * Not Owned. + */ + AlfCustomInitDataBase* mCustomData; + }; + + + } // namespace Alf + +#endif // I_ALFWIDGET_H + +// End of File