/*
* Copyright (c) 2005-2008 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description: Header file for CGSPluginInterface class.
*
*/
#ifndef GSPLUGININTERFACE_H
#define GSPLUGININTERFACE_H
// System includes
#include <gsframeworkrsc.rsg> // For default icons
#include <gsfwicon.mbg>
#include <aknview.h>
#include <aknViewAppUi.h>
#include <gulicon.h>
#include <AknsUtils.h>
#include <aknViewAppUi.h>
#include <data_caging_path_literals.hrh>
// Constant for plugin interface:
const TUid KGSPluginInterfaceUid = { 0x10207236 };
// Constant for listbox icon type:
const TUid KGSIconTypeLbxItem = { 0x10207357 };
// Constant for listbox settings item icon type:
const TUid KGSIconTypeLbxSettingsItem = { 0x102750C5 };
// Constant for tab icon type:
const TUid KGSIconTypeTab = { 0x10207358 };
// Constant for icon in D-Column:
const TUid KGSIconTypeDColumn = { 0x10207359 };
// Constant for indexing (iOrder):
const TInt KGSPluginNotIndexed = -1;
_LIT( KGSDefaultIconFileName, "Z:Gsfwicon.mbm" );
/**
* This enum is used for defining custom operations types.
*/
enum TGSCustomOperationType
{
// This operation type returns current status of the plugin's view.
// If the plugin's view is active, ETrue will be returned, otherwise
// EFalse. Currently supported by GSStandbyPlugin.
EGSCustomOperationViewActive = 1
};
/**
* Used by GetValue(). These are the keys for retrieving a specific
* value. This enum can be extended to provide other values as well as
* long as the original keys are not changed.
*/
enum TGSPluginValueKeys
{
// Value for this key is the localized string to be shown in the second row
// of a listbox item. Plugins providing second row of text should provide
// value for this key. Second row of list item text is used for following
// listbox types:
// - EGSListBoxTypeSingleLarge
// - EGSListBoxTypeDouble2Large.
// For plugins listed in these listbox types, second row value can either
// be defined or left empty.
EGSPluginKeySettingsItemValueString = 1,
// Localized string to be used in case of custom MSK and menu activation
// item. See TGSMenuActivationItems.
EGSCustomMenuActivationText
};
/**
* Used by PluginItemType(). These enumerations define the desired appearance
* of the plugin in a parent plugin's listbox. Please notice that the parent
* listbox type cannot be altered by a child plugin so plugins using these must
* be aware of the parent plugin listbox type. Safest alternative is to leave
* default implementation for ItemType() in which case EGSItemTypeSingleLarge is
* used. This should fit most of the listbox types. Additionall types can be
* implemented and defined as long as the old enumerations will not be changed.
*
* Different type of items are handled differently:
* - In case of CAknView type items, such as EGSItemTypeSingleLarge and
* EGSItemTypeSetting, the plugin's DoActivate() is called when user selects
* the item.
* - In case of items supporting dialogs, such as EGSItemTypeSettingDialog and
* EGSItemTypeSettingIconDialog, HandleSelection() is called instead of
* DoActivate().
*
* Item types can be described in a matrix:
* X: Normal list tems with large icon,
* settings items,
* settings items with icon
* Y: Items providing CAknView - activated by DoActivate(),
* items providing dialog - activated by HandleSelection()
*
* All combinations of these are not allowed/supported.
*/
enum TGSListboxItemTypes
{
// CAknSingleLargeStyleListBox item:
// Caption of the item is a descriptor from GetCaptionL().
// Icon is from CreateIconL( KGSIconTypeLbxItem ).
EGSItemTypeSingleLarge = 1, // Default
// CAknSettingStyleListBox item providing a CAknView:
// 1st row content is a descriptor from GetCaptionL()
// 2nd row content is a descriptor (can be empty string id needed) from
// GetValue( ..., EGSPluginKeySettingsItemValueString ).
EGSItemTypeSetting,
// CAknSettingStyleListBox item providing a CAknView:
// 1st row content is a descriptor from GetCaptionL()
// 2nd row content is a icon from CreateIconL( KGSIconTypeLbxSettingsItem )
// GetValue(, EGSPluginKeySettingsItemValueString ).
EGSItemTypeSettingIcon,
// CAknSettingStyleListBox item launching a dialog:
// 1st row content is a descriptor from GetCaptionL()
// 2nd row content is a descriptor (can be empty string id needed) from
// GetValue( ..., EGSPluginKeySettingsItemValueString ).
EGSItemTypeSettingDialog,
// CAknSingleLargeStyleListBox item launching a dialog:
// Caption of the item is a descriptor from GetCaptionL().
// Icon is from CreateIconL( KGSIconTypeLbxItem ).
EGSItemTypeSingleLargeDialog
};
/**
* These are used to define the type of the menu item which opens the selected
* plugin. By default, parent plugin's menu has 'Open' item for child plugins.
* If parent plugin's menu must have 'Change' instead of 'Open' for activating
* the plugin, use EGSMenuActivationItemChange. This functionality is just for
* the visual aspects for views in GS - requested by UI design. Plugins are
* handled logically similarly regardless this value.
*/
enum TGSMenuActivationItems
{
// Default - will use the item defined in menu resource.
EGSMenuActivationItemDefault = 0,
// Menu should contain 'Open' Item.
EGSMenuActivationItemOpen = 1,
// Menu should contain 'Change' item.
EGSMenuActivationItemChange,
// Menu should contain custom text which is defined by GetValue() function:
// GetValue( EGSCustomMenuActivationText, ... );
// NOTE: When this custom menu item is selected, used menu command ID is
// EGSCmdAppChange. This might be checked in for example plugin's
// HandleCommand(). If text is empy, MSK is empty and there's no
// corresponding item in options menu.
EGSMenuActivationItemCustom
};
/**
* Selection types. Used in HandleSelection().
*/
enum TGSSelectionTypes
{
// User selected the item by pressing selection key.
EGSSelectionBySelectionKey = 1,
// User selected the item by selecting a command from the menu.
EGSSelectionByMenu
};
/**
* Interface class for GS plugin. All GS plugins will implement this class.
*
* The main functionality GS framework will use from CAknView is:
* -DoActivate()
* -DoDeactivate()
* -Id()
* functions.
*
* Id() function must return the value of the plugin implementation UID. This
* means that the main view of the plugin will have the same UID as the plugin
* implementation. This will prevent multiple plugins from having same view
* UIDs as their main view. If plugin has more views, it is plugin's
* responsibility to ensure that the UIDs of the other views are unique. This
* can be done for example reserving a unique UID from Symbian.
*
* Most of the functions have implementation using default values. Override
* functions if different values or implementations are desired.
*
* CGSPluginInterface UID = 0x10207236
*
* See GSFWViewUIDs.h for plugin UIDs.
*
* Plugin implementation UID will be used when defining the parent view of a
* plugin. If plugin belongs to application settings view, set the
* ApplicationSettingsView plugin implementation Uid as a value in the plugin's
* default_data field in plugin's implementation info resource file.
*
* Needed libraries (at least):
* GSEcomPlugin.lib
* GSFramework.lib
* egul.lib
* aknskins.lib
* efsrv.lib
*
* @lib GSFramework.lib
* @since Series60_3.1
*/
class CGSPluginInterface: public CAknView
{
// CGSPluginLoader accesses iOrder which should not be accessed outside.
friend class CGSPluginLoader;
public: // Constructors & destructors
/**
* Creates new GS plugin having the given UID.
* Uses Leave code KErrNotFound if implementation is not found.
*
* @param aImplementationUid Implementation UID of the plugin to be
* created.
* @param aInitParams Plugin's initialization parameters. Make sure you know
* what the plugin expects as initialization parameters. This
* should be an agreement between the plugin client and the
* plugin. Parameter can be used for example as sharing a common
* data model between multiple plugins.
*/
IMPORT_C static CGSPluginInterface* NewL(
const TUid aImplementationUid,
TAny* aInitParams );
/**
* Destructor
*/
IMPORT_C ~CGSPluginInterface();
public: // New
/**
* Method for getting caption of this plugin. This should be the
* localized name of the settings view to be shown in parent view.
*
* @param aCaption pointer to Caption variable
*/
virtual void GetCaptionL( TDes& aCaption ) const = 0;
/**
* Function for getting plugin's value for a certain key.
* Override to provide own functionality.
*
* @param aKey Key for the value to be retrieved.
* @parem aValue Value for the given gey in TDes format.
*/
IMPORT_C virtual void GetValue( const TGSPluginValueKeys aKey,
TDes& aValue );
/**
* This function is called in case plugin is an item in a settings
* listbox and user selects the item. Override this if plugin needs to
* provide functionality for item selection.
*
* Default implementation activates the plugin.
* @param aSelectionType Defines how user selected the plugin. See
* TGSSelectionTypes.
*/
IMPORT_C virtual void HandleSelection(
const TGSSelectionTypes aSelectionType );
/**
* This defines the appearance of the plugin in a parent plugin listbox.
* Default value is EGSItemTypeSingleLarge. Please notice that the
* parent listbox type cannot be defined by a child plugin so plugins
* using these must be aware of the parent plugin listbox type.
*
* @return Desired listbox presentation and functional type for the
* plugin.
*/
IMPORT_C virtual TGSListboxItemTypes ItemType();
/**
* This function is only used for child plugins. Defines the dynamic
* menu item that activates this plugin from parent plugin. This menu
* item will override the item defined in resource file. Normally
* 'Open' is used to open the child plugin. Override this to change the
* activation to for example 'Change'. TGSMenuActivationItems defines the
* different possible menu items that can be used to open this plugin.
*
* Note: This also defines MSK. Menu activation item and MSK have
* identical label and behaviour. An exception to this is
* when custom text is empty: in this case MSK is empty but there
* is no item in options menu (no empty item in menu).
*
* @ return Type of the menu item and MSK that should activate this
* child plugin from parent plugin.
*/
IMPORT_C virtual TGSMenuActivationItems MenuActivationItem();
/**
* Creates a new icon of desired type. Override this to provide custom
* icons. Othervise default icon is used for KGSIconTypeLbxItem. Other
* icons are empty. Ownership of the created icon is transferred to the
* caller.
* NOTE: Return NULL if icon is not to be displayed.
*
* Icon type UIDs (use these defined constants):
* KGSIconTypeLbxItem - ListBox item icon.
* KGSIconTypeLbxSettingsItem - Settings item icon.
* KGSIconTypeTab - Tab icon.
* KGSIconTypeDColumn - Small icon in D-column.
*
* @param aIconType UID Icon type UID of the icon to be created.
* @return Pointer of the icon or NULL.
*/
IMPORT_C virtual CGulIcon* CreateIconL( const TUid aIconType );
/**
* Method for reading the ID of the plugin provider category. See
* TGSPluginProviderCategory. PluginProviderCategory can be used for
* sorting plugins.
*
* Default value is EGSPluginProvider3rdParty. Override this function
* to change the category.
*
* @return Plugin provider category ID defined by
* TGSPluginProviderCategory
*/
IMPORT_C virtual TInt PluginProviderCategory() const;
/**
* Reserved for future use/plugin's custom functionality. This can be
* overwritten if plugin needs to have custom functionality which cannot
* be fulfilled otherwise.
*
* Use TGSCustomOperationType enumeration as aParam1 to
* define operation type.
*/
IMPORT_C virtual TAny* CustomOperationL( TAny* aParam1, TAny* aParam2 );
/**
* Method for checking, if plugin should be visible and used in GS FW.
* (for example shown in listbox of the parent view).
*
* On default plugin is visible. Overwrite this function to enable or
* disable your plugin dynamically.
*
* @return ETrue if plugin should be visible in GS.
* @return EFalse if plugin should not be visible in GS.
*/
IMPORT_C virtual TBool Visible() const;
/**
* Resets plugin's selected item index if this is supported. Default
* implementation does nothing. This is needed when navigating from
* child plugin back to parent plugin. In this case child plugin should
* reset selected index in its listbox.
*/
IMPORT_C virtual void ResetSelectedItemIndex();
/**
* Sets the Index of the plugin in listbox. Used for CGSPluginLoader. Default
* value is KGSPluginNotIndexed which means not ordered. This value is
* read, if defined, from the opaque_data field of the plugin's resource
* definition. Index starts from 0.
*/
IMPORT_C void SetOrder( TInt aOrder );
/**
* In case plug-in is loaded outside GS application and CGSPluginLoader,
* cleaning up plug-in's ECOM resources must be done manually.
*
* Example:
* CGSPluginInterface* myPlugin = CGSPluginInterface::NewL(...);
* REComSession::DestroyedImplementation( myPlugin->GetEcomDestructorKey() );
* delete myPlugin;
*
* @return UID of the plug-in instance which can be used to free dependent ECOM resources.
*/
IMPORT_C TUid GetEcomDestructorKey();
protected: // New
/**
* C++ constructor.
*/
IMPORT_C CGSPluginInterface();
public: // Enumerations
/**
* Category of the plugin provider. Provider's type affects the sorting
* of the plugins. Type EGSPluginProvider3rdParty plugins are allowed
* to be loaded only by Applications-plugin. Other categories may exist
* but they should be used only internally.
**/
enum TGSPluginProviderCategory
{
EGSPluginProviderOEM = 1,
EGSPluginProviderOperator = 2,
EGSPluginProvider3rdParty = 3
};
private: // Data
// ECOM plugin instance UID.
TUid iDtor_ID_Key;
/**
* Index of the plugin in listbox. Used for CGSPluginLoader. Default
* value is KGSPluginNotIndexed which means not ordered. This value is
* read, if defined, from the opaque_data field of the plugin's resource
* definition. Index starts from 0.
*/
TInt iOrder;
};
#endif // GSPLUGININTERFACE_H
//End of file