mulwidgets/alfviewwidget/inc/alfviewwidget.h
changeset 0 e83bab7cf002
equal deleted inserted replaced
-1:000000000000 0:e83bab7cf002
       
     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*/