/*
* Copyright (c) 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: Base class definitions for items displayed in AppMngr2
*
*/
#ifndef C_APPMNGR2INFOBASE_H
#define C_APPMNGR2INFOBASE_H
#include <e32base.h> // CBase
#include <eikmenup.h> // CEikMenuPaneItem::SData
class CAppMngr2Runtime;
enum TAppMngr2Location
{
EAppMngr2LocationPhone,
EAppMngr2LocationMemoryCard,
EAppMngr2LocationMassStorage
};
/**
* CAppMngr2InfoBase is the base class for objects representing:
* - installed applications and
* - installation packages (aka installation files).
*
* Installed applications and installation packages are displayed in the
* Appliction Manager UI using the data that Runtime plug-ins provide with
* CAppMngr2InfoBase derived objects. Application Manager gets the data via
* GetInstalledAppsL() and GetInstallationFilesL() metods in CAppMngr2Runtime
* class.
*
* CAppMngr2InfoBase contains the common functionality for both installed
* applications and installation packages. Derived classes CAppMngr2AppInfo
* and CAppMngr2PackageInfo are placeholders for more specific functionality.
*
* CAppMngr2InfoBase, as well as CAppMngr2AppInfo and CAppMngr2PackageInfo,
* are abstracts classes. Runtime plug-ins must provide the actual implementation
* by using derived classes.
*
* @lib appmngr2pluginapi.lib
* @since S60 v5.1
*/
class CAppMngr2InfoBase : public CBase
{
public: // constructor and destructor
void ConstructL();
~CAppMngr2InfoBase();
public: // new functions
/**
* Reference to the CAppMngr2Runtime object of this plugin.
*
* @return CAppMngr2Runtime& Runtime object
*/
IMPORT_C CAppMngr2Runtime& Runtime() const;
/**
* Icon index of this item (installed application or installation package).
*
* Items are displayed in a list in the UI. Each item has an icon image,
* two labels (name and details) and an optional small indicator icon.
* IconIndex() method provides index for the icon image.
*
* Icon index can be either:
* - index to icon array loaded in CAppMngr2Runtime::LoadIconsL() method
* - special value EAppMngr2UseSpecificIcon defined in AppMngr2Common.hrh
*
* If item has a specific icon that no other items use, return value
* EAppMngr2UseSpecificIcon and load the specific icon via SpecificIconL().
*
* There are no default icons, each plug-in must provide implementation
* for IconIndex() method.
*
* @return TInt Icon index
*/
virtual TInt IconIndex() const = 0;
/**
* Optional specific icon for this item.
*
* Returns new icon specific for the item. Note that this method is not
* used unless IconIndex() method returns EAppMngr2UseSpecificIcon value.
*
* The caller of this method is responsible to delete the returned
* icon object.
*
* Default implementation leaves with KErrNotSupported. Plug-in must
* override it if IconIndex() returns EAppMngr2UseSpecificIcon value.
*
* If the same icon bitmap is used in many items, it is more efficient
* to load it once in CAppMngr2Runtime::LoadIconsL() and return icon
* indexes form IconIndex() method.
*
* @return CGulIcon Item specific icon
*/
IMPORT_C virtual CGulIcon* SpecificIconL() const;
/**
* Name of this item.
*
* Items are displayed in a list in the UI. The list uses two labels
* (name and details) for each item. Descriptor that the Name() method
* returns is displayed as the first label (the 1st line of the item).
*
* @return const TDesC& Displayable name
*/
virtual const TDesC& Name() const = 0;
/**
* Details (size) of this item.
*
* Items are displayed in a list in the UI. The list uses two labels
* (name and details) for each item. Descriptor that the Details() method
* returns is displayed as the second label (the 2nd line of the item).
*
* Plug-ins can use SizeStringWithUnitsL() method to create details
* string to display the item size in UI.
*
* @returns const TDesC& Displayable additional information line
*/
virtual const TDesC& Details() const = 0;
/**
* Indicator icon index of this item.
*
* Icon index can be either:
* - default icon index defined in TAppMngr2IconIndex in AppMngr2Common.hrh
* - index to icon array loaded in CAppMngr2Runtime::LoadIconsL() method
* - special value EAppMngr2UseSpecificIcon defined in AppMngr2Common.hrh
*
* Default implementation returns the default icon indexes based on
* the value of iLocation member variable, so plug-ins usually does not
* need to override this method.
*
* If EAppMngr2UseSpecificIcon value is returned, SpecificIndicatorIconL()
* method is called to get the indicator icon.
*
* @return TInt Index to the icon array, or a TAppMngr2IconIndex value
*/
IMPORT_C virtual TInt IndicatorIconIndex() const;
/**
* Optional specific indicator icon for this item.
*
* Returns new indicator icon specific for the item. Note that this
* method is not used unless IndicatorIconIndex() method returns
* special EAppMngr2UseSpecificIcon value.
*
* The caller of this method is responsible to delete the returned
* icon object.
*
* Default implementation leaves with KErrNotSupported. Plug-in must
* override it if IndicatorIconIndex() returns EAppMngr2UseSpecificIcon.
*
* If the same icon bitmap is used in many items, it is more efficient
* to load it once in CAppMngr2Runtime::LoadIconsL() and return icon
* indexes form IconIndex() method.
*
* @return CGulIcon Item specific icon
*/
IMPORT_C virtual CGulIcon* SpecificIndicatorIconL() const;
/**
* ShowOnTop highlight status of this item.
*
* Returns ETrue if this item should be highlighted (e.g. displayed
* separately on top of other items in installation files/installed
* applications list). All items are displayed in alphabetical order.
* If ShowOnTop flag is set, then the item is displayed before other
* items (or in completely separate list of highligted items). All
* separately displayed items are listed in alphabetical order too.
*
* @return TBool ETrue, if this item should be displayed separately
*/
IMPORT_C TBool IsShowOnTop() const;
/**
* Optional specific menu items for this item.
*
* If the item supports specific menu commands, return the menu pane
* data. Plug-in can use ReadMenuItemDataFromResourceL() method to
* read menu pane data from resources. Menu commands are run via
* HandleCommandL() method.
*
* The caller of this method is responsible to delete the returned
* CEikMenuPaneItem::SData data structs.
*
* Default implementation is empty.
*
* @param aMenuCmds Array where plug-in specific menu items are added
*/
IMPORT_C virtual void GetMenuItemsL( RPointerArray<CEikMenuPaneItem::SData>& aMenuCmds );
/**
* Enable generic menu commands for this item.
*
* Generic menu commands are defined in TAppMngr2GenericCommands enum in
* AppMngr2Common.hrh. Generic commands are hidden from the menu if the
* currently selected item does not support them. Return ETrue for those
* command ids that are supported by this item. Generic commands are
* run via HandleCommandL() method.
*
* @param aCmdId Generic command id
* @return TBool ETrue if command aCmdId is supported
*/
IMPORT_C virtual TBool SupportsGenericCommand( TInt aCmdId );
/**
* Optional specific middle softkey command for this item.
*
* If the item supports specific middle softkey command, return TBUF
* resource id (for the command label) and command id. Item specific
* command is run via HandleCommandL() method when user presses the
* middle softkey.
*
* Default middle softkey command is used, if plug-in does not override it.
*
* @param aResourceId Command label to be displayed in UI (TBUF resource)
* @param aCommandId Command id to be passed to HandleCommandL
*/
IMPORT_C virtual void GetMiddleSoftkeyCommandL( TInt& aResourceId, TInt& aCommandId );
/**
* Starts asynchronously a user invoked command.
*
* The command can be a generic one or specific to the plug-in. The ids
* for the generic commands are defined in AppMngr2Common.hrh (see the
* enumeration TAppMngr2GenericCommand). The plug-in specific commands
* are defined via GetMenuItemsL() and GetMiddleSoftkeyCommandL() methods.
*
* The caller of this method must call HandleCommandResultL() after the
* asynchronous request has been completed.
*
* This asynchronous request must be completed properly using the method
* User::RequestComplete() even if the command itself has been implemented
* in synchronous manner.
*
* @param aCommandId Id of the command to be run
* @param aStatus Active object request status
*/
virtual void HandleCommandL( TInt aCommandId, TRequestStatus& aStatus ) = 0;
/**
* Handles the completion result of an asynchronous command.
*
* This method is provided so that the plug-in may decide upon handling
* possible errors encountered during the command processing (note that
* the completion status is received directly by the caller of the method
* HandleCommandL() and not by this plug-in). These actions may include
* for example closing open sessions and deleting objects.
*
* This function should leave if an error note should be displayed in
* the UI (e.g. KErrNoMemory). Note that the result may be KErrCancel
* or SwiUI::KSWInstErrUserCancel if the user cancelled the operation.
*
* @param aResult Completion code, KErrNone or some error code
*/
virtual void HandleCommandResultL( TInt aResult ) = 0;
/**
* Cancels the current asynchronous command.
*
* This method may be called at any time when an asynchronous command
* is started using HandleCommandL() method. It must cancel the running
* command as quickly as possible.
*/
virtual void CancelCommand() = 0;
/**
* Utility function to create displayable string that contains size
* followed by kilobyte (kB), megabyte (MB) or gigabyte (GB) units.
*
* Size is rounded and formatted using the relevant unit, for example
* SizeStringWithUnitsL( 5120 ) returns "5 kB".
*
* The caller of this method is responsible to delete the returned string.
*
* @param aSizeInBytes Item size
* @return HBufC* New string that contains displayable size string
*/
IMPORT_C HBufC* SizeStringWithUnitsL( TInt64 aSizeInBytes );
/**
* Utility function to construct CEikMenuPaneItem from MENU_ITEM resource.
*
* @param aResourceId MENU_ITEM resource id
* @param aMenuItem CEikMenuPaneItem::SData struct that is filled in
*/
IMPORT_C void ReadMenuItemDataFromResourceL( TInt aResourceId,
CEikMenuPaneItem::SData& aMenuItem );
/**
* Returns the location of installation file or installed application.
*
* Remote drives are not supported. Derived class must fill in the
* iLocation member variable to provide data for this function.
*
* @return TAppMngr2Location Location of the item
*/
IMPORT_C TAppMngr2Location Location() const;
/**
* Returns the drive where installation file is located, or where
* installed application is installed.
*
* Derived class must fill in the iLocationDrive member variable
* to provide data for this function.
*
* @return TDriveUnit Drive where the item is located
*/
IMPORT_C TDriveUnit LocationDrive() const;
protected: // new functions
/**
* Constructor, not exported because used via CAppMngr2AppInfo and CAppMngr2PackageInfo
*/
CAppMngr2InfoBase( CAppMngr2Runtime& aRuntime, RFs& aFsSession );
protected: // data
/**
* Location of this item.
*
* Default implementation of IndicatorIconIndex() function uses this
* value to return the default indicator icon index. See also the
* Location() function defined above.
*/
TAppMngr2Location iLocation;
/**
* Drive of this item.
*
* Location drive defines the drive where this item resides (either
* installation package is stored, or application is installed).
* CAppMngr2InfoIterator uses this value to display the drive
* in "Details" dialog. See also the LocationDrive() function
* defined above.
*/
TDriveUnit iLocationDrive;
/**
* ShowOnTop (highlight) flag.
*
* If ShowOnTop flag is ETrue, the item is highlighted in UI. It
* may be displayed on top of other items in installed application
* or installation files list, or it may be displayed in separate
* list of highlighted items.
*
* For example, untrusted installed applications can be highlighted.
*
*
* The
* item should indicate the reason why it is not displayed normally
* when iShowOnTop is set to ETrue (e.g. use special icon).
* See also the IsShowOnTop() function defined above.
*/
TBool iShowOnTop;
/**
* File server session, provided by framework when item is created.
*/
RFs& iFs;
private: // data
/**
* Reference to CAppMngr2Runtime class for this item.
* See also the Runtime() function defined above.
*/
CAppMngr2Runtime& iRuntime;
};
#endif // C_APPMNGR2INFOBASE_H