1 /*

     2 * Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Widget interface with utilities for container widget.

    15 *

    16 */

    17 

    18 

    19 #ifndef ALFCONTAINERWIDGET_H

    20 #define ALFCONTAINERWIDGET_H

    21 

    22 #include "alf/ialfcontainerwidget.h"

    23 #include <alf/alflayout.h>

    24 

    25 // Forward declarations

    26 class CAlfEnv;

    27 

    28 namespace Alf

    29 {

    30 

    31 // Forward declarations

    32 class AlfWidget;

    33 

    34 /**

    35  * Container widget implementation.

    36  * 

    37  * Container widget can be used to contain other widgets in an arbitrary layout.

    38  * To create a container widget see CAlfContainerWidgetFactoryPlugin class.

    39  * 

    40  * Container widget creates a control group with ID 0 and stores it's control

    41  * in it. It will also append all added widget controls into the same control group

    42  * unless the added widget control is added to its own control group.

    43  */

    44 class AlfContainerWidget : public IAlfContainerWidget

    45 {

    46 public:

    47 

    48     /**

    49      * Default constructor.

    50      * 

    51      * Use CAlfContainerWidgetFactoryPlugin::CreateProduct() to instantiate a container

    52      * widget.

    53      * 

    54      * @param aWidgetName The widget name or ID to be assigned to this widget.

    55      * @param aContainer Container widget in which this container is contained. 

    56      * @param aEnv UI Accelerator Environment instance to which the widget is created. 

    57      * @param aNode Runtime declaration of the widget 

    58      * @param aFilePath Path to XML file describing the presentation of the widget 

    59      */

    60 	AlfContainerWidget(	const char* aWidgetName, 

    61 						IAlfContainerWidget& aContainer, 

    62 						CAlfEnv& aEnv,

    63 						DuiNode* aNode,

    64 						const char* aFilePath);

    65     

    66     /**

    67      * Default destructor.

    68      */

    69 	virtual ~AlfContainerWidget();

    70     

    71     // From Alf::IAlfWidget base class

    72     

    73     /**

    74      * Getter for the control. The ownership is not passed.

    75      *

    76      * @since S60 5.0

    77      * @return The control of this widget, or NULL if the control is not specified.

    78      */

    79     virtual CAlfWidgetControl* control() const;

    80     

    81     /**

    82      * getter for the parent container. The ownership is not passed.

    83      * @return the parent container or NULL if the widget is the root-widget.

    84      */

    85     virtual IAlfContainerWidget* parent() const;

    86 

    87     /**

    88      * Setter for the control. The control is owned by the Alfred environment.

    89      * The previously set control can be destroyed when new control is set.

    90      * 

    91      * The set control is added to the control group of this container widget.

    92      * The set control is removed from it's previous control group.

    93      *

    94      * @since S60 5.0

    95      * @param aControl The control for this widget.

    96      * @param aDeletePreviousControl A boolean to indicate whether the previously set control

    97      * 								 is to be destroyed when this method is called.

    98      */

    99     virtual void setControl(CAlfWidgetControl* aControl, bool aDeletePreviousControl = true);

   100 

   101     /**

   102      * Getter for the model. The ownership is not passed.

   103      *

   104      * @since S60 5.0

   105      * @return The model of this widget, or NULL if the model is not specified.

   106      */

   107     virtual IAlfModel* model();

   108 

   109     /**

   110      * Setter for the model. Ownership is passed and the old model is released.

   111      *

   112      * @since S60 5.0

   113      * @param aModel The model for this widget.

   114      * @param aTakeOwnership Whether takes ownership of model or not

   115      */

   116     virtual void setModel(IAlfModel* aModel, bool aTakeOwnership = true);

   117     

   118     /**

   119      * Get the name of the widget instance.

   120      *

   121      * @since S60 5.0

   122      * @return Widget name

   123      */

   124     virtual const char* widgetName() const;   

   125     

   126     /**

   127      * Sets/Releases the Focus from child widget of container.

   128      * Does not set the actual focused status in roster.

   129      *

   130      * @since S60 5.0

   131      * @param aFocus boolean value for focused status

   132      */

   133     virtual void setChildFocus(bool aFocus);    

   134     

   135     /** 

   136      * Sets the presentation for the widget using presentation XML file.

   137      * Destroys any existing presentation.

   138      * @param aFilePath Path to XML file describing the presentation 

   139      *                  of the widget. Not Owned.

   140      * @exception AlfWidgetException if no visualization node available 

   141      *                               in Presentation XML or if no control

   142      *                               is associated with the widget.

   143      * @exception bad_alloc 

   144      * @since S60 ?S60_version

   145      * @return void.

   146      */

   147     virtual void setPresentation(const char* aFilePath);      

   148 

   149     // From Alf::IAlfContainerWidget base class

   150     

   151     /**

   152      * Returns total number of widgets contained by this container.

   153      *

   154      * @return int Total number of widgets.

   155      */

   156     virtual int widgetCount() const;

   157     

   158     /**

   159      * Adds a child widget to the container.

   160      * 

   161      * Ownership of the widget is transferred to this container

   162      * object.

   163      * 

   164      * The control of the added widget is appended to the control group of

   165      * this container widget unless the control already is appended to

   166      * another control group.

   167      *

   168      * @param  aWidget Child widget to be added to container.

   169      */

   170     virtual void addWidget(IAlfWidget& aWidget);

   171 

   172     /**

   173      * Returns child widget at given index.

   174      * 

   175      * If index is not found returns null.

   176      *

   177      * @param  aIndex Index of widget to be returned.

   178      * @return Widget at given index or null if not found.

   179      */

   180     virtual IAlfWidget* getWidget(int aIndex) const;

   181     

   182     /**

   183      * Returns the child index, when given the child widget.

   184      *

   185      * @param  aWidget child widget, which index is returned 

   186      * @return the index of the child widget, or -1, if widget is not child of this container.

   187      */

   188     virtual int getWidgetIndex(IAlfWidget& aWidget) const;

   189 

   190     /**

   191      * Removes the child widget from given index.

   192      * 

   193      * This will destroy the widget object at the given index.

   194      *

   195      * @param aIndex Index from which widget has to be removed.

   196      */

   197     virtual void removeWidget(int aIndex);

   198     

   199     /**

   200      * Sets the base layout of container widget.

   201      *

   202      * @param aLayout New base layout of container widegt.

   203      */

   204     virtual void applyLayout(IAlfLayoutManager& aLayout);

   205 

   206     // From Alf::IAlfInterfaceBase base class

   207 

   208     /**

   209      * Interface getter.

   210      * Derived classes should always call the base class method

   211      * from the overridden MakeInterface.

   212      *

   213      * @since S60 5.0

   214      * @param aType The type id of the queried interface.

   215      * @return The queried interface, or NULL if the interface is not

   216      *         supported or available.

   217      */

   218     virtual IAlfInterfaceBase* makeInterface(const IfId& aType);

   219 

   220 private:

   221 	/**

   222 	 * Constructs widget from declaration.

   223 	 *

   224 	 * @param aNode declaration node.

   225 	 */

   226 	void constructComponentsFromNode();

   227 

   228 	/**

   229 	 * Constructs widget from declaration.

   230 	 *

   231 	 * @param aNode declaration node.

   232 	 */

   233 	void processTreeRecursively();

   234 

   235 	/**

   236 	 * Constructs widget using the presentation XML.

   237 	 *

   238 	 * @param aFilePath Path to XML file describing the presentation of the widget.

   239 	 */

   240 	void constructFromPresentationXML(const char *aFilePath);

   241 

   242 	/**

   243 	 * Constructs control for widget

   244 	 *

   245 	 */

   246 	void constructDefault();

   247 	

   248 	/**

   249      * Sets default layout mgr.

   250      */

   251     void setDefaultLayoutManager();

   252 private:

   253 

   254 	/** Pointer to the adaptee AlfWidget - object. */

   255 	auto_ptr<AlfWidget> mWidget;

   256 	

   257 	/**

   258 	 * UI Accelerator Environment where this widget is used.

   259 	 * Not owned.

   260 	 */

   261 	CAlfEnv& mEnv;

   262 

   263 };

   264 

   265 }

   266 

   267 #endif /*ALFCONTAINERWIDGET_H*/