mulwidgets/alfcontainerwidget/inc/alfcontainerwidget.h
branchRCL_3
changeset 25 4ea6f81c838a
parent 23 514d98f21c43
child 26 0e9bb658ef58
equal deleted inserted replaced
23:514d98f21c43 25:4ea6f81c838a
     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*/