1 /*

     2 * Copyright (c) 2005-2008 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:   Header file for CGSPluginInterface class.

    15 *

    16 */

    17 

    18 

    19 #ifndef GSPLUGININTERFACE_H

    20 #define GSPLUGININTERFACE_H

    21 

    22 // System includes

    23 #include <GSFrameworkRsc.rsg> // For default icons

    24 #include <gsfwicon.mbg>

    25 

    26 #include <aknview.h>

    27 #include <aknViewAppUi.h>

    28 #include <gulicon.h>

    29 #include <AknsUtils.h>

    30 #include <aknViewAppUi.h>

    31 #include <data_caging_path_literals.hrh>

    32 

    33 // Constant for plugin interface:

    34 const TUid KGSPluginInterfaceUid        = { 0x10207236 };

    35 

    36 // Constant for listbox icon type:

    37 const TUid KGSIconTypeLbxItem           = { 0x10207357 };

    38 // Constant for listbox settings item icon type:

    39 const TUid KGSIconTypeLbxSettingsItem   = { 0x102750C5 };

    40 // Constant for tab icon type:

    41 const TUid KGSIconTypeTab               = { 0x10207358 };

    42 // Constant for icon in D-Column:

    43 const TUid KGSIconTypeDColumn           = { 0x10207359 };

    44 

    45 

    46 // Constant for indexing (iOrder):

    47 const TInt KGSPluginNotIndexed      = -1;

    48 

    49 _LIT( KGSDefaultIconFileName, "Z:Gsfwicon.mbm" );

    50 

    51 /**

    52 * This enum is used for defining custom operations types.

    53 */

    54 enum TGSCustomOperationType

    55     {

    56     // This operation type returns current status of the plugin's view.

    57     // If the plugin's view is active, ETrue will be returned, otherwise

    58     // EFalse. Currently supported by GSStandbyPlugin.

    59     EGSCustomOperationViewActive = 1

    60     };

    61 

    62 /**

    63 * Used by GetValue(). These are the keys for retrieving a specific

    64 * value. This enum can be extended to provide other values as well as

    65 * long as the original keys are not changed.

    66 */

    67 enum TGSPluginValueKeys

    68     {

    69     // Value for this key is the localized string to be shown in the second row

    70     // of a listbox item. Plugins providing second row of text should provide

    71     // value for this key. Second row of list item text is used for following

    72     // listbox types:

    73     //  - EGSListBoxTypeSingleLarge

    74     //  - EGSListBoxTypeDouble2Large.

    75     // For plugins listed in these listbox types, second row value can either

    76     // be defined or left empty.

    77     EGSPluginKeySettingsItemValueString = 1,

    78     // Localized string to be used in case of custom MSK and menu activation

    79     // item. See TGSMenuActivationItems.

    80     EGSCustomMenuActivationText

    81     };

    82 

    83 /**

    84 * Used by PluginItemType(). These enumerations define the desired appearance

    85 * of the plugin in a parent plugin's listbox. Please notice that the parent

    86 * listbox type cannot be altered by a child plugin so plugins using these must

    87 * be aware of the parent plugin listbox type. Safest alternative is to leave

    88 * default implementation for ItemType() in which case EGSItemTypeSingleLarge is

    89 * used. This should fit most of the listbox types. Additionall types can be

    90 * implemented and defined as long as the old enumerations will not be changed.

    91 *

    92 * Different type of items are handled differently:

    93 * - In case of CAknView type items, such as EGSItemTypeSingleLarge and

    94 *   EGSItemTypeSetting, the plugin's DoActivate() is called when user selects

    95 *   the item.

    96 * - In case of items supporting dialogs, such as EGSItemTypeSettingDialog and

    97 *   EGSItemTypeSettingIconDialog, HandleSelection() is called instead of

    98 *   DoActivate().

    99 *

   100 * Item types can be described in a matrix:

   101 * X: Normal list tems with large icon,

   102 *    settings items,

   103 *    settings items with icon

   104 * Y: Items providing CAknView - activated by DoActivate(),

   105 *    items providing dialog - activated by HandleSelection()

   106 *

   107 * All combinations of these are not allowed/supported.

   108 */

   109 enum TGSListboxItemTypes

   110     {

   111     // CAknSingleLargeStyleListBox item:

   112     // Caption of the item is a descriptor from GetCaptionL().

   113     // Icon is from CreateIconL( KGSIconTypeLbxItem ).

   114     EGSItemTypeSingleLarge = 1, // Default

   115     // CAknSettingStyleListBox item providing a CAknView:

   116     // 1st row content is a descriptor from GetCaptionL()

   117     // 2nd row content is a descriptor (can be empty string id needed) from

   118     //    GetValue( ..., EGSPluginKeySettingsItemValueString ).

   119     EGSItemTypeSetting,

   120     // CAknSettingStyleListBox item providing a CAknView:

   121     // 1st row content is a descriptor from GetCaptionL()

   122     // 2nd row content is a icon from CreateIconL( KGSIconTypeLbxSettingsItem )

   123     // GetValue(, EGSPluginKeySettingsItemValueString ).

   124     EGSItemTypeSettingIcon,

   125     // CAknSettingStyleListBox item launching a dialog:

   126     // 1st row content is a descriptor from GetCaptionL()

   127     // 2nd row content is a descriptor (can be empty string id needed) from

   128     //    GetValue( ..., EGSPluginKeySettingsItemValueString ).

   129     EGSItemTypeSettingDialog,

   130     // CAknSingleLargeStyleListBox item launching a dialog:

   131     // Caption of the item is a descriptor from GetCaptionL().

   132     // Icon is from CreateIconL( KGSIconTypeLbxItem ).

   133     EGSItemTypeSingleLargeDialog

   134     };

   135 

   136 /**

   137 * These are used to define the type of the menu item which opens the selected

   138 * plugin. By default, parent plugin's menu has 'Open' item for child plugins.

   139 * If parent plugin's menu must have 'Change' instead of 'Open' for activating

   140 * the plugin, use EGSMenuActivationItemChange. This functionality is just for

   141 * the visual aspects for views in GS - requested by UI design. Plugins are

   142 * handled logically similarly regardless this value.

   143 */

   144 enum TGSMenuActivationItems

   145     {

   146     // Default - will use the item defined in menu resource.

   147     EGSMenuActivationItemDefault = 0,

   148     // Menu should contain 'Open' Item.

   149     EGSMenuActivationItemOpen = 1,

   150     // Menu should contain 'Change' item.

   151     EGSMenuActivationItemChange,

   152     // Menu should contain custom text which is defined by GetValue() function:

   153     // GetValue( EGSCustomMenuActivationText, ... );

   154     // NOTE: When this custom menu item is selected, used menu command ID is

   155     // EGSCmdAppChange. This might be checked in for example plugin's

   156     // HandleCommand(). If text is empy, MSK is empty and there's no

   157     // corresponding item in options menu.

   158     EGSMenuActivationItemCustom

   159     };

   160 

   161 /**

   162 * Selection types. Used in HandleSelection().

   163 */

   164 enum TGSSelectionTypes

   165     {

   166     // User selected the item by pressing selection key.

   167     EGSSelectionBySelectionKey = 1,

   168     // User selected the item by selecting a command from the menu.

   169     EGSSelectionByMenu

   170     };

   171 

   172 /**

   173 * Interface class for GS plugin. All GS plugins will implement this class.

   174 *

   175 * The main functionality GS framework will use from CAknView is:

   176 * -DoActivate()

   177 * -DoDeactivate()

   178 * -Id()

   179 * functions.

   180 *

   181 * Id() function must return the value of the plugin implementation UID. This

   182 * means that the main view of the plugin will have the same UID as the plugin

   183 * implementation. This will prevent multiple plugins from having same view

   184 * UIDs as their main view. If plugin has more views, it is plugin's

   185 * responsibility to ensure that the UIDs of the other views are unique. This

   186 * can be done for example reserving a unique UID from Symbian.

   187 *

   188 * Most of the functions have implementation using default values. Override

   189 * functions if different values or implementations are desired.

   190 *

   191 * CGSPluginInterface UID = 0x10207236

   192 *

   193 * See GSFWViewUIDs.h for plugin UIDs.

   194 *

   195 * Plugin implementation UID will be used when defining the parent view of a

   196 * plugin. If plugin belongs to application settings view, set the

   197 * ApplicationSettingsView plugin implementation Uid as a value in the plugin's

   198 * default_data field in plugin's implementation info resource file.

   199 *

   200 * Needed libraries (at least):

   201 * GSEcomPlugin.lib

   202 * GSFramework.lib

   203 * egul.lib

   204 * aknskins.lib

   205 * efsrv.lib

   206 *

   207 * @lib GSFramework.lib

   208 * @since Series60_3.1

   209 */

   210 class CGSPluginInterface: public CAknView

   211     {

   212 

   213     // CGSPluginLoader accesses iOrder which should not be accessed outside.

   214     friend class CGSPluginLoader;

   215 

   216     public: // Constructors & destructors

   217 

   218         /**

   219         * Creates new GS plugin having the given UID.

   220         * Uses Leave code KErrNotFound if implementation is not found.

   221         *

   222         * @param aImplementationUid Implementation UID of the plugin to be

   223         *        created.

   224         * @param aInitParams Plugin's initialization parameters. Make sure you know

   225         *        what the plugin expects as initialization parameters. This

   226         *        should be an agreement between the plugin client and the

   227         *        plugin. Parameter can be used for example as sharing a common

   228         *        data model between multiple plugins.

   229         */

   230         IMPORT_C static CGSPluginInterface* NewL(

   231             const TUid aImplementationUid,

   232             TAny* aInitParams );

   233 

   234         /**

   235         * Destructor

   236         */

   237         IMPORT_C ~CGSPluginInterface();

   238 

   239     public: // New

   240 

   241         /**

   242         * Method for getting caption of this plugin. This should be the

   243         * localized name of the settings view to be shown in parent view.

   244         *

   245         * @param aCaption pointer to Caption variable

   246         */

   247         virtual void GetCaptionL( TDes& aCaption ) const = 0;

   248 

   249         /**

   250         * Function for getting plugin's value for a certain key.

   251         * Override to provide own functionality.

   252         *

   253         * @param aKey Key for the value to be retrieved.

   254         * @parem aValue Value for the given gey in TDes format.

   255         */

   256         IMPORT_C virtual void GetValue( const TGSPluginValueKeys aKey,

   257                                         TDes& aValue );

   258 

   259         /**

   260         * This function is called in case plugin is an item in a settings

   261         * listbox and user selects the item. Override this if plugin needs to

   262         * provide functionality for item selection.

   263         *

   264         * Default implementation activates the plugin.

   265         * @param aSelectionType Defines how user selected the plugin. See

   266         *        TGSSelectionTypes.

   267         */

   268         IMPORT_C virtual void HandleSelection(

   269             const TGSSelectionTypes aSelectionType );

   270 

   271         /**

   272         * This defines the appearance of the plugin in a parent plugin listbox.

   273         * Default value is EGSItemTypeSingleLarge. Please notice that the

   274         * parent listbox type cannot be defined by a child plugin so plugins

   275         * using these must be aware of the parent plugin listbox type.

   276         *

   277         * @return Desired listbox presentation and functional type for the

   278         *         plugin.

   279         */

   280         IMPORT_C virtual TGSListboxItemTypes ItemType();

   281 

   282         /**

   283         * This function is only used for child plugins. Defines the dynamic

   284         * menu item that activates this plugin from parent plugin. This menu

   285         * item will override the item defined in resource file. Normally

   286         * 'Open' is used to open the child plugin. Override this to change the

   287         * activation to for example 'Change'. TGSMenuActivationItems defines the

   288         * different possible menu items that can be used to open this plugin.

   289         *

   290         * Note: This also defines MSK. Menu activation item and MSK have

   291         *       identical label and behaviour. An exception to this is

   292         *       when custom text is empty: in this case MSK is empty but there

   293         *       is no item in options menu (no empty item in menu).

   294         *

   295         * @ return Type of the menu item and MSK that should activate this

   296         *          child plugin from parent plugin.

   297         */

   298         IMPORT_C virtual TGSMenuActivationItems MenuActivationItem();

   299 

   300         /**

   301         * Creates a new icon of desired type. Override this to provide custom

   302         * icons. Othervise default icon is used for KGSIconTypeLbxItem. Other

   303         * icons are empty. Ownership of the created icon is transferred to the

   304         * caller.

   305         * NOTE: Return NULL if icon is not to be displayed.

   306         *

   307         * Icon type UIDs (use these defined constants):

   308         * KGSIconTypeLbxItem            - ListBox item icon.

   309         * KGSIconTypeLbxSettingsItem    - Settings item icon.

   310         * KGSIconTypeTab                - Tab icon.

   311         * KGSIconTypeDColumn            - Small icon in D-column.

   312         *

   313         * @param aIconType UID Icon type UID of the icon to be created.

   314         * @return Pointer of the icon or NULL.

   315         */

   316         IMPORT_C virtual CGulIcon* CreateIconL( const TUid aIconType );

   317 

   318         /**

   319         * Method for reading the ID of the plugin provider category. See

   320         * TGSPluginProviderCategory. PluginProviderCategory can be used for

   321         * sorting plugins.

   322         *

   323         * Default value is EGSPluginProvider3rdParty. Override this function

   324         * to change the category.

   325         *

   326         * @return Plugin provider category ID defined by

   327         *         TGSPluginProviderCategory

   328         */

   329         IMPORT_C virtual TInt PluginProviderCategory() const;

   330 

   331         /**

   332         * Reserved for future use/plugin's custom functionality. This can be

   333         * overwritten if plugin needs to have custom functionality which cannot

   334         * be fulfilled otherwise.

   335         *

   336         * Use TGSCustomOperationType enumeration as aParam1 to

   337         * define operation type.

   338         */

   339         IMPORT_C virtual TAny* CustomOperationL( TAny* aParam1, TAny* aParam2 );

   340 

   341         /**

   342         * Method for checking, if plugin should be visible and used in GS FW.

   343         * (for example shown in listbox of the parent view).

   344         *

   345         * On default plugin is visible. Overwrite this function to enable or

   346         * disable your plugin dynamically.

   347         *

   348         * @return ETrue if plugin should be visible in GS.

   349         * @return EFalse if plugin should not be visible in GS.

   350         */

   351         IMPORT_C virtual TBool Visible() const;

   352 

   353         /**

   354         * Resets plugin's selected item index if this is supported. Default

   355         * implementation does nothing. This is needed when navigating from

   356         * child plugin back to parent plugin. In this case child plugin should

   357         * reset selected index in its listbox.

   358         */

   359         IMPORT_C virtual void ResetSelectedItemIndex();

   360 

   361         /**

   362         * Sets the Index of the plugin in listbox. Used for CGSPluginLoader. Default

   363         * value is KGSPluginNotIndexed which means not ordered. This value is

   364         * read, if defined, from the opaque_data field of the plugin's resource

   365         * definition. Index starts from 0.

   366         */

   367         IMPORT_C void SetOrder( TInt aOrder );

   368 

   369         /**

   370         * In case plug-in is loaded outside GS application and CGSPluginLoader,

   371         * cleaning up plug-in's ECOM resources must be done manually.

   372         *

   373         * Example:

   374         * CGSPluginInterface* myPlugin = CGSPluginInterface::NewL(...);

   375         * REComSession::DestroyedImplementation( myPlugin->GetEcomDestructorKey() );

   376         * delete myPlugin;

   377         *

   378         * @return UID of the plug-in instance which can be used to free dependent ECOM resources.

   379         */

   380         IMPORT_C TUid GetEcomDestructorKey();

   381 

   382     protected: // New

   383 

   384         /**

   385         * C++ constructor.

   386         */

   387         IMPORT_C CGSPluginInterface();

   388 

   389     public: // Enumerations

   390 

   391         /**

   392         * Category of the plugin provider. Provider's type affects the sorting

   393         * of the plugins. Type EGSPluginProvider3rdParty plugins are allowed

   394         * to be loaded only by Applications-plugin. Other categories may exist

   395         * but they should be used only internally.

   396         **/

   397         enum TGSPluginProviderCategory

   398             {

   399             EGSPluginProviderOEM        = 1,

   400             EGSPluginProviderOperator   = 2,

   401             EGSPluginProvider3rdParty   = 3

   402             };

   403 

   404     private: // Data

   405 

   406         // ECOM plugin instance UID.

   407         TUid iDtor_ID_Key;

   408 

   409         /**

   410         * Index of the plugin in listbox. Used for CGSPluginLoader. Default

   411         * value is KGSPluginNotIndexed which means not ordered. This value is

   412         * read, if defined, from the opaque_data field of the plugin's resource

   413         * definition. Index starts from 0.

   414         */

   415         TInt iOrder;

   416 

   417     };

   418 

   419 #endif // GSPLUGININTERFACE_H

   420 //End of file