1 /*

     2 * Copyright (c) 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:   Base class definitions for items displayed in AppMngr2

    15 *

    16 */

    17 

    18 

    19 #ifndef C_APPMNGR2INFOBASE_H

    20 #define C_APPMNGR2INFOBASE_H

    21 

    22 #include <e32base.h>                    // CBase

    23 #include <eikmenup.h>                   // CEikMenuPaneItem::SData

    24 

    25 class CAppMngr2Runtime;

    26 

    27 enum TAppMngr2Location

    28     {

    29     EAppMngr2LocationPhone,

    30     EAppMngr2LocationMemoryCard,

    31     EAppMngr2LocationMassStorage

    32     };

    33 

    34 /**

    35  * CAppMngr2InfoBase is the base class for objects representing:

    36  * - installed applications and

    37  * - installation packages (aka installation files).

    38  * 

    39  * Installed applications and installation packages are displayed in the

    40  * Appliction Manager UI using the data that Runtime plug-ins provide with

    41  * CAppMngr2InfoBase derived objects. Application Manager gets the data via

    42  * GetInstalledAppsL() and GetInstallationFilesL() metods in CAppMngr2Runtime

    43  * class.

    44  * 

    45  * CAppMngr2InfoBase contains the common functionality for both installed

    46  * applications and installation packages. Derived classes CAppMngr2AppInfo

    47  * and CAppMngr2PackageInfo are placeholders for more specific functionality.  

    48  * 

    49  * CAppMngr2InfoBase, as well as CAppMngr2AppInfo and CAppMngr2PackageInfo,

    50  * are abstracts classes. Runtime plug-ins must provide the actual implementation

    51  * by using derived classes.

    52  * 

    53  * @lib appmngr2pluginapi.lib

    54  * @since S60 v5.1

    55  */

    56 class CAppMngr2InfoBase : public CBase

    57     {

    58 public:     // constructor and destructor

    59     void ConstructL();

    60     ~CAppMngr2InfoBase();

    61 

    62 public:     // new functions

    63     /**

    64      * Reference to the CAppMngr2Runtime object of this plugin.

    65      * 

    66      * @return CAppMngr2Runtime&  Runtime object

    67      */

    68     IMPORT_C CAppMngr2Runtime& Runtime() const;

    69     

    70     /**

    71      * Icon index of this item (installed application or installation package).

    72      * 

    73      * Items are displayed in a list in the UI. Each item has an icon image,

    74      * two labels (name and details) and an optional small indicator icon.

    75      * IconIndex() method provides index for the icon image.

    76      * 

    77      * Icon index can be either:

    78      * - index to icon array loaded in CAppMngr2Runtime::LoadIconsL() method

    79      * - special value EAppMngr2UseSpecificIcon defined in AppMngr2Common.hrh

    80      * 

    81      * If item has a specific icon that no other items use, return value

    82      * EAppMngr2UseSpecificIcon and load the specific icon via SpecificIconL().

    83      * 

    84      * There are no default icons, each plug-in must provide implementation

    85      * for IconIndex() method.

    86      * 

    87      * @return TInt  Icon index

    88      */

    89     virtual TInt IconIndex() const = 0;

    90 

    91     /**

    92      * Optional specific icon for this item.

    93      * 

    94      * Returns new icon specific for the item. Note that this method is not

    95      * used unless IconIndex() method returns EAppMngr2UseSpecificIcon value.

    96      * 

    97      * The caller of this method is responsible to delete the returned

    98      * icon object.

    99      * 

   100      * Default implementation leaves with KErrNotSupported. Plug-in must

   101      * override it if IconIndex() returns EAppMngr2UseSpecificIcon value.

   102      * 

   103      * If the same icon bitmap is used in many items, it is more efficient

   104      * to load it once in CAppMngr2Runtime::LoadIconsL() and return icon

   105      * indexes form IconIndex() method.

   106      *  

   107      * @return CGulIcon  Item specific icon

   108      */

   109     IMPORT_C virtual CGulIcon* SpecificIconL() const;

   110 

   111     /**

   112      * Name of this item. 

   113      * 

   114      * Items are displayed in a list in the UI. The list uses two labels

   115      * (name and details) for each item. Descriptor that the Name() method

   116      * returns is displayed as the first label (the 1st line of the item).

   117      * 

   118      * @return const TDesC&  Displayable name

   119      */

   120     virtual const TDesC& Name() const = 0;

   121 

   122     /**

   123      * Details (size) of this item.

   124      * 

   125      * Items are displayed in a list in the UI. The list uses two labels

   126      * (name and details) for each item. Descriptor that the Details() method

   127      * returns is displayed as the second label (the 2nd line of the item).

   128      * 

   129      * Plug-ins can use SizeStringWithUnitsL() method to create details

   130      * string to display the item size in UI.

   131      * 

   132      * @returns const TDesC&  Displayable additional information line

   133      */

   134     virtual const TDesC& Details() const = 0;

   135 

   136     /**

   137      * Indicator icon index of this item.

   138      * 

   139      * Icon index can be either:

   140      * - default icon index defined in TAppMngr2IconIndex in AppMngr2Common.hrh

   141      * - index to icon array loaded in CAppMngr2Runtime::LoadIconsL() method

   142      * - special value EAppMngr2UseSpecificIcon defined in AppMngr2Common.hrh

   143      * 

   144      * Default implementation returns the default icon indexes based on

   145      * the value of iLocation member variable, so plug-ins usually does not

   146      * need to override this method.

   147      * 

   148      * If EAppMngr2UseSpecificIcon value is returned, SpecificIndicatorIconL()

   149      * method is  called to get the indicator icon.

   150      * 

   151      * @return TInt  Index to the icon array, or a TAppMngr2IconIndex value

   152      */

   153     IMPORT_C virtual TInt IndicatorIconIndex() const;

   154 

   155     /**

   156      * Optional specific indicator icon for this item.

   157      * 

   158      * Returns new indicator icon specific for the item. Note that this

   159      * method is not used unless IndicatorIconIndex() method returns

   160      * special EAppMngr2UseSpecificIcon value.

   161      * 

   162      * The caller of this method is responsible to delete the returned

   163      * icon object.

   164      * 

   165      * Default implementation leaves with KErrNotSupported. Plug-in must

   166      * override it if IndicatorIconIndex() returns EAppMngr2UseSpecificIcon.

   167      * 

   168      * If the same icon bitmap is used in many items, it is more efficient

   169      * to load it once in CAppMngr2Runtime::LoadIconsL() and return icon

   170      * indexes form IconIndex() method.

   171      * 

   172      * @return CGulIcon  Item specific icon

   173      */

   174     IMPORT_C virtual CGulIcon* SpecificIndicatorIconL() const;

   175 

   176     /**

   177      * ShowOnTop highlight status of this item.

   178      * 

   179      * Returns ETrue if this item should be highlighted (e.g. displayed

   180      * separately on top of other items in installation files/installed

   181      * applications list). All items are displayed in alphabetical order.

   182      * If ShowOnTop flag is set, then the item is displayed before other

   183      * items (or in completely separate list of highligted items). All

   184      * separately displayed items are listed in alphabetical order too. 

   185      * 

   186      * @return TBool  ETrue, if this item should be displayed separately

   187      */

   188     IMPORT_C TBool IsShowOnTop() const;

   189 

   190     /**

   191      * Optional specific menu items for this item.

   192      * 

   193      * If the item supports specific menu commands, return the menu pane

   194      * data. Plug-in can use ReadMenuItemDataFromResourceL() method to

   195      * read menu pane data from resources. Menu commands are run via

   196      * HandleCommandL() method.

   197      * 

   198      * The caller of this method is responsible to delete the returned

   199      * CEikMenuPaneItem::SData data structs.

   200      * 

   201      * Default implementation is empty. 

   202      * 

   203      * @param aMenuCmds  Array where plug-in specific menu items are added

   204      */

   205     IMPORT_C virtual void GetMenuItemsL( RPointerArray<CEikMenuPaneItem::SData>& aMenuCmds );

   206 

   207     /**

   208      * Enable generic menu commands for this item.

   209      * 

   210      * Generic menu commands are defined in TAppMngr2GenericCommands enum in

   211      * AppMngr2Common.hrh. Generic commands are hidden from the menu if the

   212      * currently selected item does not support them. Return ETrue for those

   213      * command ids that are supported by this item. Generic commands are

   214      * run via HandleCommandL() method.

   215      * 

   216      * @param aCmdId Generic command id

   217      * @return TBool ETrue if command aCmdId is supported

   218      */

   219     IMPORT_C virtual TBool SupportsGenericCommand( TInt aCmdId );

   220 

   221     /**

   222      * Optional specific middle softkey command for this item.

   223      *

   224      * If the item supports specific middle softkey command, return TBUF

   225      * resource id (for the command label) and command id. Item specific

   226      * command is run via HandleCommandL() method when user presses the

   227      * middle softkey. 

   228      * 

   229      * Default middle softkey command is used, if plug-in does not override it.

   230      *

   231      * @param aResourceId  Command label to be displayed in UI (TBUF resource)

   232      * @param aCommandId  Command id to be passed to HandleCommandL 

   233      */

   234     IMPORT_C virtual void GetMiddleSoftkeyCommandL( TInt& aResourceId, TInt& aCommandId );

   235 

   236     /**

   237      * Starts asynchronously a user invoked command.

   238      * 

   239      * The command can be a generic one or specific to the plug-in. The ids

   240      * for the generic commands are defined in AppMngr2Common.hrh (see the 

   241      * enumeration TAppMngr2GenericCommand). The plug-in specific commands 

   242      * are defined via GetMenuItemsL() and GetMiddleSoftkeyCommandL() methods. 

   243      *

   244      * The caller of this method must call HandleCommandResultL() after the

   245      * asynchronous request has been completed.

   246      *

   247      * This asynchronous request must be completed properly using the method 

   248      * User::RequestComplete() even if the command itself has been implemented 

   249      * in synchronous manner.

   250      *

   251      * @param aCommandId  Id of the command to be run

   252      * @param aStatus  Active object request status

   253      */

   254     virtual void HandleCommandL( TInt aCommandId, TRequestStatus& aStatus ) = 0;

   255 

   256     /**

   257      * Handles the completion result of an asynchronous command. 

   258      *

   259      * This method is provided so that the plug-in may decide upon handling

   260      * possible errors encountered during the command processing (note that 

   261      * the completion status is received directly by the caller of the method

   262      * HandleCommandL() and not by this plug-in). These actions may include 

   263      * for example closing open sessions and deleting objects.

   264      *

   265      * This function should leave if an error note should be displayed in

   266      * the UI (e.g. KErrNoMemory). Note that the result may be KErrCancel

   267      * or SwiUI::KSWInstErrUserCancel if the user cancelled the operation.

   268      *

   269      * @param aResult  Completion code, KErrNone or some error code

   270      */

   271     virtual void HandleCommandResultL( TInt aResult ) = 0;

   272 

   273     /**

   274      * Cancels the current asynchronous command.

   275      * 

   276      * This method may be called at any time when an asynchronous command

   277      * is started using HandleCommandL() method. It must cancel the running

   278      * command as quickly as possible.  

   279      */

   280     virtual void CancelCommand() = 0;

   281     

   282     /**

   283      * Utility function to create displayable string that contains size

   284      * followed by kilobyte (kB), megabyte (MB) or gigabyte (GB) units.

   285      * 

   286      * Size is rounded and formatted using the relevant unit, for example

   287      * SizeStringWithUnitsL( 5120 ) returns "5 kB".

   288      * 

   289      * The caller of this method is responsible to delete the returned string.

   290      * 

   291      * @param aSizeInBytes  Item size

   292      * @return HBufC*  New string that contains displayable size string 

   293      */

   294     IMPORT_C HBufC* SizeStringWithUnitsL( TInt64 aSizeInBytes );

   295 

   296     /**

   297      * Utility function to construct CEikMenuPaneItem from MENU_ITEM resource.

   298      * 

   299      * @param aResourceId  MENU_ITEM resource id

   300      * @param aMenuItem  CEikMenuPaneItem::SData struct that is filled in

   301      */ 

   302     IMPORT_C void ReadMenuItemDataFromResourceL( TInt aResourceId,

   303             CEikMenuPaneItem::SData& aMenuItem );

   304 

   305     /**

   306      * Returns the location of installation file or installed application.

   307      * 

   308      * Remote drives are not supported. Derived class must fill in the

   309      * iLocation member variable to provide data for this function.

   310      * 

   311      * @return TAppMngr2Location  Location of the item

   312      */ 

   313     IMPORT_C TAppMngr2Location Location() const;

   314 

   315     /**

   316      * Returns the drive where installation file is located, or where

   317      * installed application is installed.

   318      * 

   319      * Derived class must fill in the iLocationDrive member variable

   320      * to provide data for this function.

   321      * 

   322      * @return TDriveUnit  Drive where the item is located

   323      */

   324     IMPORT_C TDriveUnit LocationDrive() const;

   325     

   326 protected:  // new functions

   327     /**

   328      * Constructor, not exported because used via CAppMngr2AppInfo and CAppMngr2PackageInfo

   329      */

   330     CAppMngr2InfoBase( CAppMngr2Runtime& aRuntime, RFs& aFsSession );

   331 

   332 protected:  // data

   333     /**

   334      * Location of this item.

   335      * 

   336      * Default implementation of IndicatorIconIndex() function uses this

   337      * value to return the default indicator icon index. See also the

   338      * Location() function defined above.

   339      */

   340     TAppMngr2Location iLocation;

   341     

   342     /**

   343      * Drive of this item.

   344      * 

   345      * Location drive defines the drive where this item resides (either

   346      * installation package is stored, or application is installed).

   347      * CAppMngr2InfoIterator uses this value to display the drive

   348      * in "Details" dialog. See also the LocationDrive() function

   349      * defined above.

   350      */

   351     TDriveUnit iLocationDrive;

   352     

   353     /**

   354      * ShowOnTop (highlight) flag.

   355      * 

   356      * If ShowOnTop flag is ETrue, the item is highlighted in UI. It

   357      * may be displayed on top of other items in installed application

   358      * or installation files list, or it may be displayed in separate

   359      * list of highlighted items.

   360      * 

   361      * For example, untrusted installed applications can be highlighted.

   362      * 

   363      * 

   364      * The

   365      * item should indicate the reason why it is not displayed normally

   366      * when iShowOnTop is set to ETrue (e.g. use special icon).

   367      * See also the IsShowOnTop() function defined above.

   368      */

   369     TBool iShowOnTop;

   370 

   371     /**

   372      * File server session, provided by framework when item is created.

   373      */

   374     RFs& iFs;

   375     

   376 private:    // data

   377     /**

   378      * Reference to CAppMngr2Runtime class for this item.

   379      * See also the Runtime() function defined above. 

   380      */

   381     CAppMngr2Runtime& iRuntime;

   382     };

   383 

   384 #endif // C_APPMNGR2INFOBASE_H

   385