/*

* 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.

     * 

     */

    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