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:   View widget interface.

    15 *

    16 */

    17 

    18 

    19 #ifndef IALF_VIEWWIDGET_H

    20 #define IALF_VIEWWIDGET_H

    21 

    22 #include <e32base.h>

    23 #include <alf/ialfcontainerwidget.h>

    24 

    25 //Forward Declaration

    26 class TAknsItemID;

    27 class CAlfDisplay;

    28 

    29 namespace Alf

    30     {

    31 

    32 namespace alfviewwidget

    33     {

    34 static const IfId ident =

    35     {

    36     0, "viewwidget"

    37     };

    38 

    39     }

    40 

    41 /**

    42  * An interface for the view widget.

    43  *

    44  *  @since S60 ?S60_version

    45  */

    46 

    47 class IAlfViewWidget : public IAlfContainerWidget

    48     {

    49 

    50 public:

    51     /**

    52      * Getter for the type identifier of this interface.

    53      * @return A descriptor to identify the type of this interface.

    54      *

    55      * @since S60 ?S60_version

    56      */

    57     static inline const IfId& type()

    58         {

    59         return alfviewwidget::ident;

    60         }

    61 

    62 

    63     /**

    64      * This will show the view widget. The view widget will be

    65      * shown on the top of the view stack. If the view was already

    66      * shown it will be moved on top of the view stack.

    67      *

    68      * @see getViewStackPosition()

    69      *

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

    71      *              the view will be hidden. The view is not shown, 

    72      *              till this api is called with true parameter.

    73      * @since S60 ?S60_version

    74      */

    75     virtual void show(bool aShow = true) = 0 ;

    76 	

    77     /**

    78      * API to make the view widget accept events.

    79      *

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

    81      *     default value is true

    82      * @since S60 ?S60_version

    83      */

    84     virtual void acceptEvents(bool aAccept = true) = 0 ;

    85 

    86     /**

    87      * API to enable/disable Avkon status pane

    88      *

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

    90      *     the default value is true.

    91      * @since S60 ?S60_version

    92      */

    93     virtual void enableStatusPane(bool aEnable = true) = 0;

    94 

    95     /**

    96      * API to hide/show Avkon control pane

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

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

    99      *

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

   101      *     the default value is true.

   102      * @since S60 ?S60_version

   103      */

   104     virtual void enableControlPane(bool aEnable = true) = 0;

   105 

   106     /**

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

   108      *

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

   110      *                        false otherwise.

   111      * @since S60 ?S60_version

   112      */

   113     virtual void useSkinBackground(bool aSkinBackground = true) = 0;

   114 

   115     /**

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

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

   118      *

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

   120      *

   121      * @since S60 ?S60_version

   122      */

   123     virtual void setSkinBackground(TAknsItemID aSkinID) = 0;

   124 

   125     /**

   126      * API to check whether the view is shown

   127      *

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

   129      *

   130      * @since S60 ?S60_version

   131      */

   132     virtual bool shown() = 0;

   133     

   134     /**

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

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

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

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

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

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

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

   142      * top-most.

   143      *

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

   145      *

   146      * @see show()

   147      * 

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

   149      */    

   150     virtual int getViewStackPosition() const = 0;

   151 

   152     /**

   153      * API to check whether the view accepts events

   154      *

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

   156      *

   157      * @since S60 ?S60_version

   158      */

   159     virtual bool eventsAccepted() = 0;

   160 

   161     /**

   162      * API to check whether the status pane is enabled

   163      *

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

   165      *

   166      * @since S60 ?S60_version

   167      */

   168     virtual bool statusPaneEnabled() = 0;

   169 

   170     /**

   171      * API to check whether the control pane is enabled

   172      *

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

   174      *

   175      * @since S60 ?S60_version

   176      */

   177     virtual bool controlPaneEnabled() = 0;

   178 

   179     /**

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

   181      * or not

   182      *

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

   184      *

   185      * @since S60 ?S60_version

   186      */

   187     virtual bool usingSkinBackground() = 0;

   188 

   189     /**

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

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

   192      * being used.

   193      *

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

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

   196      *         this info was never set.

   197      *         See IAlfViewWidget::setSkinBackground()

   198      *

   199      * @since S60 ?S60_version

   200      */

   201     virtual TAknsItemID skinBackground() = 0;

   202     

   203     /**

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

   205      * This will set the alfdisplay area with param passed

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

   207      * view full screen or application rect

   208      *

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

   210      *                      displayed

   211      *

   212      * @since S60 ?S60_version

   213      */

   214     virtual void setRect(const TRect& aDisplayRect) = 0;

   215 

   216     /**

   217      * Virtual destructor.

   218      */

   219     virtual ~IAlfViewWidget () {}

   220 

   221     };

   222 	

   223 /**

   224  *  Structure to store information required to instantiate a view widget

   225  *  via the widget factory mechanism.

   226  *  A pointer to this structure is casted to a void pointer and sent to the

   227  *  factory plugin during the view widget construction.

   228  */

   229 struct AlfViewWidgetInitData

   230     {

   231     /**

   232      * Owner environment for the widget

   233      */

   234     CAlfEnv* mEnv;

   235 

   236     /**

   237      * Display pointer

   238      */

   239     CAlfDisplay* mDisplay;

   240 

   241     /**

   242      * Widget instance ID.This uniquely identifies every widget instance

   243      * and is its name.

   244      * @see AlfWidget::Widgetname()

   245      */

   246     const char* mWidgetId;

   247     

   248     /**

   249      * Control group ID that will be used to create a new control group

   250      * and append the view widget into. 

   251      */

   252     int mControlGroupId;

   253 

   254     /**

   255      * Pointer to node in declaration containing information for the widget.

   256      */

   257     DuiNode* mNode;

   258     

   259     /**

   260      * XML file name containing the declaration for the presention of the widget. 

   261      */

   262     const char* mFilePath;

   263 

   264     /**

   265      * Pointer to custom data passed via factory mechanism

   266      * Not Owned.

   267      */

   268     AlfCustomInitDataBase* mCustomData;  

   269     };	

   270 

   271 	}//end of namespace

   272 

   273 #endif // IALF_VIEWWIDGET_H

   274 //End Of File