1 coneresloader.h

     1 /*

     2 * Copyright (c) 2002-2006 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Cone Resource Loader API enables adding and removing 

    15 *                localized resource files into the CONE environment.

    16 *

    17 */

    18 

    19 

    20 #ifndef CONERESLOADER_H

    21 #define CONERESLOADER_H

    22 

    23 // forward declarations

    24 class CCoeEnv;

    25 

    26 /** 

    27 * Class encapsulates methods for opening and closing localised resource files

    28 * in the CONE environment. The actual reading of resources from an opened 

    29 * resource file is done using various CCoeEnv provided resource-reading 

    30 * methods. Cone Resource Loader API consist of the RConeResourceLoader class.

    31 *

    32 * Only one resource at a time may be open by one RConeResourceLoader instance. 

    33 * You can use several RConeResourceLoader instances for accessing several 

    34 * resources simultaneously or use one instance and close the previous resource

    35 * before opening a new one.

    36 *

    37 * The implementation uses BaflUtils::NearestLanguageFile to search for

    38 * a localised resource in proper search order.

    39 * 

    40 * Usage example:  

    41 *

    42 * @code

    43 *  #include <ConeResLoader.h>  

    44 *

    45 *  // Get CCoeEnv instance

    46 *  CEikonEnv* eikEnv = CEikonEnv::Static();

    47 *

    48 *  // Initialize loader

    49 *  RConeResourceLoader rLoader(eikEnv);

    50 *

    51 *  // Open resource file

    52 *  _LIT( KSampleResourceFileName, "Z:\\System\\Apps\\sample\\sample.rsc" );

    53 *  TFileName fileName(KSampleResourceFileName);

    54 *  rLoader.OpenL(fileName);

    55 *

    56 *  // Push resource loader to cleanup stack, so that it will always be properly 

    57 *  // closed when popped.

    58 *  CleanupClosePushL(rLoader);

    59 *

    60 *  // Read a resource   

    61 *  iSomeArray = eikEnv->ReadDesC16ArrayResourceL(R_SOME_RESOURCE);

    62 *

    63 *  // Pop and destroy rLoader from stack. 

    64 *  // This also calls close on rLoader since CleanupClosePushL was used.

    65 *  CleanupStack::PopAndDestroy(); // rLoader

    66 *

    67 * @endcode

    68 *

    69 * @lib commonengine.lib

    70 * @since S60 2.0

    71 */

    72 class RConeResourceLoader

    73     {

    74     public:

    75         /**

    76          * Constructor. 

    77          *

    78          * @param aEnv is a reference to Control environment in which resource

    79          * is loaded.

    80          */

    81         IMPORT_C RConeResourceLoader(CCoeEnv& aEnv);

    82 

    83         /**

    84          * Opens the resource file for reading. Only one resource may be open 

    85          * at a time. Panics if this instance already has a file open. 

    86          * The implementation uses BaflUtils::NearestLanguageFile to search 

    87          * for a localized resource file in proper search order.

    88          * 

    89          * @param aFileName is the resource file name to open. This parameter

    90          * value is changed to the best matching language file found. The drive

    91          * letter is required in the filename.

    92          * @return a Symbian OS error code.

    93          *

    94          * @panic KErrNotSupported The instance already has a file open.

    95          */

    96         IMPORT_C TInt Open(TFileName& aFileName);

    97 

    98         /**

    99          * Opens the resource file for reading. Only one resource may be open 

   100          * at a time. Leaves if this instance already has a file open.

   101          * The implementation uses BaflUtils::NearestLanguageFile to search

   102          * for a localized resource file in proper search order.

   103          * 

   104          * @param aFileName Reference for resource file name. Please

   105          *                  note that drive letter is required ! 

   106          *

   107          * @leave KErrNotSupported The instance already has a file open.

   108          */

   109         IMPORT_C void OpenL(TFileName& aFileName);

   110 

   111 

   112         /**

   113          * Closes the opened resource file, if one is open. Does nothing if no

   114          * file has been opened. New resource file may be opened after the 

   115          * previous has been closed. Always remember to close the resource when 

   116          * finished using it.

   117          */

   118         IMPORT_C void Close();

   119 

   120     private:

   121                 

   122         // Prohibit copy constructor and assigment operator because not deriving from CBase.

   123         RConeResourceLoader(const RConeResourceLoader&);

   124         RConeResourceLoader& operator= ( const RConeResourceLoader& );

   125     

   126         // Needed for closing

   127         CCoeEnv& iEnv; 

   128         TInt iResourceFileOffset;

   129     };

   130 

   131 

   132 #endif

   133 

   134 // End of File