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 class header.

    15 *

    16 */

    17 

    18 

    19 #ifndef ALFVIEWWIDGET_H

    20 #define ALFVIEWWIDGET_H

    21 

    22 #include "alf/alfwidget.h"

    23 #include <alf/ialfviewwidget.h>

    24 #include <AknsItemID.h>

    25 #include <alf/alfeventhandler.h>

    26 #include <alf/alfenv.h>

    27 

    28 #include <osn/ustring.h>

    29 #include <osn/alfptrvector.h>

    30 // Forward declarations

    31 class CAlfControlGroup;

    32 

    33 namespace dui

    34     {

    35     class DuiNode;

    36     }

    37 

    38 namespace Alf

    39 {

    40 

    41 class AlfWidget;

    42 class AlfViewWidgetZOrderChangedObserver;

    43 

    44 /**

    45  * View widget implementation.

    46  *

    47  * View widget can be used to contain other widgets in an arbitrary layout.

    48  *

    49  * View widget creates a control group with ID passed in its constructor and

    50  * stores it's control in it.

    51  */

    52 class AlfViewWidget : public IAlfViewWidget, public MAlfActionObserver,MAlfEventHandler

    53 {

    54 public:

    55 

    56     /**

    57      * Default constructor.

    58      * 

    59      * Use AlfViewWidgetFactoryPlugin::CreateProduct() to instantiate a view

    60      * widget. View widget will create a new control group from the ID passed to this

    61      * constructor and append the view control into the control group.

    62      *

    63      * @exception AlfException Error code EInvalidArgument is thrown if a control group already

    64      *            exists with the given ID.

    65      * @exception AlfViewWidgetException with Symbian Error code if the view 

    66      *            is unable to register itself as an action observer in the 

    67      *            Alfred Environment.

    68      * 

    69      * @param aWidgetName Name of the constructed view widget.

    70      * @param aControlGroupId ID of the control group to append the view widget control into.     

    71      * @param aEnv UI Accelerator Toolkit environment in which this widget is defined.

    72      * @param aDisplay Display in which this widget is defined.

    73      */

    74 	AlfViewWidget(const char* aWidgetName, int aControlGroupId, CAlfEnv& aEnv, 

    75             CAlfDisplay& aDisplay, DuiNode* aNode=NULL, const char *aFilePath=NULL);

    76     

    77     /**

    78      * Default destructor.

    79      */

    80     virtual ~AlfViewWidget();

    81 

    82     // From Alf::IAlfWidget base class

    83 

    84     /**

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

    86      *

    87      * @since S60 5.0

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

    89      */

    90     virtual CAlfWidgetControl* control() const;

    91     

    92     /**

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

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

    95      */

    96     virtual IAlfContainerWidget* parent() const;

    97 

    98     /**

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

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

   101      *

   102      * The set control is added to the control group of this view widget.

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

   104      *

   105      * @since S60 5.0

   106      * @param aControl The control for this widget.

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

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

   109      */

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

   111 

   112     /**

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

   114      *

   115      * @since S60 5.0

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

   117      */

   118     virtual IAlfModel* model();

   119 

   120     /**

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

   122      *

   123      * @since S60 5.0

   124      * @param aModel The model for this widget.

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

   126      */

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

   128 

   129     /**

   130      * Get the name of the widget instance.

   131      *

   132      * @since S60 5.0

   133      * @return Widget name

   134      */

   135     virtual const char* widgetName() const;

   136 

   137     /**

   138      * Sets/Releases the Focus from child widget of view.

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

   140      *

   141      * @since S60 5.0

   142      * @param aFocus boolean value for focused status

   143      */

   144     virtual void setChildFocus(bool aFocus);

   145 

   146     // From Alf::IAlfContainerWidget base class

   147 

   148     /**

   149      * Returns total number of widgets contained by this view.

   150      *

   151      * @return int Total number of widgets.

   152      */

   153     virtual int widgetCount() const;

   154 

   155     /**

   156      * Adds a child widget to the view.

   157      *

   158      * Ownership of the widget is transferred to this view

   159      * object.

   160      *

   161      * @param  aWidget Child widget to be added to view.

   162      */

   163     virtual void addWidget(IAlfWidget& aWidget);

   164 

   165     /**

   166      * Returns child widget at given index.

   167      *

   168      * If index is not found returns null.

   169      *

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

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

   172      */

   173     virtual IAlfWidget* getWidget(int aIndex) const;

   174     

   175     /**

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

   177      *

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

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

   180      */

   181     virtual int getWidgetIndex(IAlfWidget& aWidget) const;

   182 

   183     /**

   184      * Removes the child widget from given index.

   185      *

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

   187      *

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

   189      */

   190     virtual void removeWidget(int aIndex);

   191 

   192     /**

   193      * Sets the base layout of view widget.

   194      *

   195      * @param aLayout New base layout of view widegt.

   196      */

   197     virtual void applyLayout(IAlfLayoutManager& aLayout);

   198 

   199     /** 

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

   201      * Destroys any existing presentation.

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

   203      *                  of the widget. Not Owned.

   204      * @exception AlfWidgetException if no visualization node available 

   205      *                               in Presentation XML or if no control

   206      *                               is associated with the widget.

   207      * @exception bad_alloc 

   208      * @since S60 ?S60_version

   209      * @return void.

   210      */

   211     virtual void setPresentation(const char* aFilePath);    

   212 

   213 

   214     //--------------------------------------------------------------------------------------//

   215     /* From IAlfViewWidget*/

   216     //--------------------------------------------------------------------------------------//

   217 

   218 

   219 	/**

   220 	 * API to show the view widget.

   221 	 * @param aShow	true if the view is to be shown, else false

   222 	 *				The view is not shown, till this api is called 

   223 	 *              with true parameter.    

   224 	 * @since S60 ?S60_version

   225 	 */

   226 	virtual void show(bool aShow = true);

   227 

   228 

   229     /**

   230      * API to make the view widget accept events.

   231      *

   232      * @param aAccept true if the view is to accept inputs, else false

   233      *     default value is true

   234      * @since S60 ?S60_version

   235      */

   236     virtual void acceptEvents(bool aAccept = true);

   237 

   238     /**

   239      * API to hide/show Avkon status pane.

   240      * If the AlfDisplay bound to the view widget does not occupy the 

   241      * entire client rectangle, this API has no effect. 

   242      *

   243      * @param aEnable true to enable the status pane, else false

   244      *        the default value is true.

   245      * @since S60 ?S60_version

   246      */

   247     virtual void enableStatusPane(bool aEnable = true);

   248 

   249     /**

   250      * API to hide/show Avkon control pane

   251      * If the AlfDisplay bound to the view widget does not occupy the 

   252      * entire client rectangle, this API has no effect.

   253      *

   254      * @param aEnable true to enable the control pane, else false

   255      *     the default value is true.

   256      * @since S60 ?S60_version

   257      */

   258     virtual void enableControlPane(bool aEnable = true);

   259 

   260     /**

   261      * API to enable/disable Avkon Skin to be used as view widget's background.

   262      *

   263      * @param aSkinBackground true if the view has to use Avkon Skin as background.

   264      *                        false otherwise.

   265      * @since S60 ?S60_version

   266      */

   267     virtual void useSkinBackground(bool aSkinBackground = true);

   268 

   269     /**

   270      * API to use Skin with the given ID to be used as view widget's background.

   271      * Also enables skin background. See IAlfViewWidget::useSkinBackground()

   272      *

   273      * @param aID Skin id of the graphics to be used in the texture.

   274      *

   275      * @since S60 ?S60_version

   276      */

   277     virtual void setSkinBackground(TAknsItemID aSkinID);

   278 

   279     /**

   280      * API to check whether the view is shown

   281      *

   282      * @return true if the view is shown, else false

   283      *

   284      * @since S60 ?S60_version

   285      */

   286     virtual bool shown();

   287     

   288     /**

   289      * Returns the position of the view on the view stack.

   290      * This tells the view Z-coordinate position relative to other views.

   291      * Top-most view returns zero. Views under that have a growing

   292      * number of position. If the view is hidden -1 is returned.

   293      * Only view widgets are taken into consideration in the position calculation.

   294      * Other control groups in the display roster are ignored. For example,

   295      * position zero doesn't mean that the control group of this view would be

   296      * top-most.

   297      *

   298      * Only top-most view is activate while all other views are being deactivate.

   299      * 

   300      * @return Position of the view, -1 if view is hidden.

   301      */

   302     virtual int getViewStackPosition() const;

   303 

   304     /**

   305      * API to check whether the view accepts events

   306      *

   307      * @return true if the view accepts events, else false

   308      *

   309      * @since S60 ?S60_version

   310      */

   311     virtual bool eventsAccepted();

   312 

   313     /**

   314      * API to check whether the status pane is enabled

   315      *

   316      * @return true if the status pane is enabled, else false

   317      *

   318      * @since S60 ?S60_version

   319      */

   320     virtual bool statusPaneEnabled();

   321 

   322     /**

   323      * API to check whether the control pane is enabled

   324      *

   325      * @return true if the control pane is enabled, else false

   326      *

   327      * @since S60 ?S60_version

   328      */

   329     virtual bool controlPaneEnabled();

   330     

   331 	/**

   332 	 * API to check whether skin info is being used for background

   333 	 * or not

   334 	 *

   335 	 * @return true if the skin info is being used, else false 

   336 	 *

   337 	 * @since S60 ?S60_version

   338 	 */

   339 	virtual bool usingSkinBackground();

   340 

   341 	/**

   342      * API to get the Avkon Skin ID being used as view widget's background.

   343      * Use IAlfViewWidget::usingSkinBackground() to check if this is 

   344      * being used.       

   345      * 

   346      * @return Avkon Skin ID being used for view's background.

   347      *         Returns an ID with major and minor fields=-1 if 

   348      *         this info was never set. 

   349      *         See IAlfViewWidget::setSkinBackground()

   350      *

   351      * @since S60 ?S60_version

   352 	 */

   353 	virtual TAknsItemID skinBackground();

   354 

   355     // From Alf::IAlfInterfaceBase base class

   356 

   357     /**

   358      * Interface getter.

   359      * Derived classes should always call the base class method

   360      * from the overridden MakeInterface.

   361      *

   362      * @since S60 5.0

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

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

   365      *         supported or available.

   366      */

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

   368     

   369     // New methods

   370     

   371     /**

   372      * Called to notify the view of view activation (view becoming top most in

   373      * z-order) or deactivation. The view can be deactivated multiple times

   374      * in a row without being reactivated.

   375      *

   376      * This method is called internally by the view widget itself.

   377      * 

   378      * @see getViewStackPosition()

   379      * 

   380      * @param aIsActivated Indicates whether view widget is activated or not

   381      */

   382     void notifyViewActivated(bool aIsActivated);

   383     

   384     //From MAlfActionObserver

   385     /**

   386      * @see MAlfActionObserver

   387      */ 

   388     void HandleActionL(const TAlfActionCommand& aActionCommand);

   389     

   390     /**

   391      * API to Set the display area of the view widget.

   392      * This will set the alfdisplay area with param passed

   393      * Client need to call this api with screen/apprect to make 

   394      * view full screen or application rect

   395      *

   396      * @param aDisplayRect: the area in which view widget should be

   397      *                      displayed

   398      *

   399      * @since S60 ?S60_version

   400      */

   401     void setRect(const TRect& aDisplayRect);

   402     

   403    /**

   404     * Updates the array which contains the name of all the children widgets

   405     * 

   406     * @param aChildName the name of a child widget

   407     */ 

   408     void setChildNameToDelete( UString aChildName );

   409     

   410 private:

   411 

   412     /**

   413      * Constructs widget from declaration.

   414      *

   415      * @param aEnv The environment for the widget.

   416      * @param aNode declaration node.

   417      */

   418     void constructComponentsFromNode(CAlfEnv& aEnv);

   419     

   420     /**

   421      * Constructs widget using the presentation XML.

   422      *

   423      * @param aEnv The environment for the widget.

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

   425      */

   426     void constructFromPresentationXML(CAlfEnv& aEnv, const char *aFilePath);

   427 

   428     /**

   429      * Constructs default widget

   430      *

   431      * @param aEnv The environment for the widget.

   432      */

   433     void constructDefault(CAlfEnv& aEnv, bool aCreateLM = true);

   434 

   435     /**

   436      * Sets default layout mgr.

   437      */

   438     void setDefaultLayoutManager();

   439     

   440     /**

   441      * Utility function

   442      */

   443     void updateBackGroundImage();

   444     

   445     /**

   446      * Updates the status pane according to the view settings.

   447      */

   448     void updateStatusPane();

   449     

   450     /**

   451      * Updates the control pane according to the view settings.

   452      */

   453     void updateControlPane();

   454     

   455     /**

   456      * Finds the focused control of this view.

   457      */

   458     CAlfControl* focusedControl();

   459     

   460     /**

   461      * from MAlfEventHandler

   462      */

   463     TBool OfferEventL(const TAlfEvent& aEvent);

   464     

   465 private:

   466 

   467     /**

   468      * AlfWidget instance, owned.

   469      */

   470     auto_ptr<AlfWidget> mWidget;

   471 

   472     /**

   473      * UI Accelerator Environment where this widget is used.

   474      * Not owned.

   475      */

   476     CAlfEnv* mEnv;

   477 

   478     /**

   479      * Display to be associated with the view.

   480      * Not owned.

   481      */

   482     CAlfDisplay* mDisplay;

   483     

   484     /**

   485 	 * Control group to contain the view widget control in.

   486 	 * Not owned.

   487 	 */

   488 	CAlfControlGroup* mControlGroup;

   489 	

   490 	/**

   491 	 * Control group order changed observer object used to activate

   492 	 * this view when necessary.

   493 	 * Owned.

   494 	 */

   495 	auto_ptr<AlfViewWidgetZOrderChangedObserver> mZOrderChangedObserver;

   496 	

   497     /**

   498 	 * Control group resource ID.

   499 	 */

   500 	TInt mControlGroupResourceId;

   501 	

   502     /**

   503      * Flag to indicate if the view is being shown or not.

   504      */

   505     bool mShown;

   506      

   507     /**

   508      * Flag to indicate if the Avkon Control Pane is shown or not.

   509      */

   510     bool mControlPaneEnabled;

   511 

   512     /**

   513      * Flag to indicate if the Avkon Status Pane is shown or not.

   514      */

   515     bool mStatusPaneEnabled;

   516 

   517     /**

   518      * Flag to indicate if the view uses skin background or not.

   519      */

   520     bool mSkinEnabled;

   521 

   522     /**

   523      * ID for skin related information to be used for background.

   524      */

   525     TAknsItemID mSkinId;   

   526 

   527     /**

   528      * Cache for ID of the child widget that is currently focused.

   529      * This is used to restore focus to the correct child when the view

   530      * is shown and to remember the focused child when the view  is hidden.

   531      */

   532     std::string mFocusedChildWidgetID;

   533     

   534     TRect mDisplayRect;

   535     

   536     /**

   537      * Stores the naame of all the children widgets

   538      */

   539     AlfPtrVector<UString> mChildWidgetName;

   540     

   541     /**

   542      * Flag to indicate whether AcquireFocus() has been called on one

   543      * of the controls.

   544      */

   545     TBool mHasFocus;

   546     };

   547 

   548     }

   549 

   550 #endif /*ALFVIEWWIDGET_H*/