epoc32/include/coneresloader.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000
branchSymbian2
changeset 2 2fe1408b6811
parent 0 061f57f2323e
child 4 837f303aceeb
permissions -rw-r--r--
Final list of Symbian^2 public API header files
williamr@2
     1
/*
williamr@2
     2
* Copyright (c) 2002-2006 Nokia Corporation and/or its subsidiary(-ies). 
williamr@2
     3
* All rights reserved.
williamr@2
     4
* This component and the accompanying materials are made available
williamr@2
     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
williamr@2
     6
* which accompanies this distribution, and is available
williamr@2
     7
* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2
     8
*
williamr@2
     9
* Initial Contributors:
williamr@2
    10
* Nokia Corporation - initial contribution.
williamr@2
    11
*
williamr@2
    12
* Contributors:
williamr@2
    13
*
williamr@2
    14
* Description:  Cone Resource Loader API enables adding and removing 
williamr@2
    15
*                localized resource files into the CONE environment.
williamr@2
    16
*
williamr@2
    17
*/
williamr@2
    18
williamr@2
    19
williamr@2
    20
#ifndef CONERESLOADER_H
williamr@2
    21
#define CONERESLOADER_H
williamr@2
    22
williamr@2
    23
// forward declarations
williamr@2
    24
class CCoeEnv;
williamr@2
    25
williamr@2
    26
/** 
williamr@2
    27
* Class encapsulates methods for opening and closing localised resource files
williamr@2
    28
* in the CONE environment. The actual reading of resources from an opened 
williamr@2
    29
* resource file is done using various CCoeEnv provided resource-reading 
williamr@2
    30
* methods. Cone Resource Loader API consist of the RConeResourceLoader class.
williamr@2
    31
*
williamr@2
    32
* Only one resource at a time may be open by one RConeResourceLoader instance. 
williamr@2
    33
* You can use several RConeResourceLoader instances for accessing several 
williamr@2
    34
* resources simultaneously or use one instance and close the previous resource
williamr@2
    35
* before opening a new one.
williamr@2
    36
*
williamr@2
    37
* The implementation uses BaflUtils::NearestLanguageFile to search for
williamr@2
    38
* a localised resource in proper search order.
williamr@2
    39
* 
williamr@2
    40
* Usage example:  
williamr@2
    41
*
williamr@2
    42
* @code
williamr@2
    43
*  #include <ConeResLoader.h>  
williamr@2
    44
*
williamr@2
    45
*  // Get CCoeEnv instance
williamr@2
    46
*  CEikonEnv* eikEnv = CEikonEnv::Static();
williamr@2
    47
*
williamr@2
    48
*  // Initialize loader
williamr@2
    49
*  RConeResourceLoader rLoader(eikEnv);
williamr@2
    50
*
williamr@2
    51
*  // Open resource file
williamr@2
    52
*  _LIT( KSampleResourceFileName, "Z:\\System\\Apps\\sample\\sample.rsc" );
williamr@2
    53
*  TFileName fileName(KSampleResourceFileName);
williamr@2
    54
*  rLoader.OpenL(fileName);
williamr@2
    55
*
williamr@2
    56
*  // Push resource loader to cleanup stack, so that it will always be properly 
williamr@2
    57
*  // closed when popped.
williamr@2
    58
*  CleanupClosePushL(rLoader);
williamr@2
    59
*
williamr@2
    60
*  // Read a resource   
williamr@2
    61
*  iSomeArray = eikEnv->ReadDesC16ArrayResourceL(R_SOME_RESOURCE);
williamr@2
    62
*
williamr@2
    63
*  // Pop and destroy rLoader from stack. 
williamr@2
    64
*  // This also calls close on rLoader since CleanupClosePushL was used.
williamr@2
    65
*  CleanupStack::PopAndDestroy(); // rLoader
williamr@2
    66
*
williamr@2
    67
* @endcode
williamr@2
    68
*
williamr@2
    69
* @lib commonengine.lib
williamr@2
    70
* @since S60 2.0
williamr@2
    71
*/
williamr@2
    72
class RConeResourceLoader
williamr@2
    73
    {
williamr@2
    74
    public:
williamr@2
    75
        /**
williamr@2
    76
         * Constructor. 
williamr@2
    77
         *
williamr@2
    78
         * @param aEnv is a reference to Control environment in which resource
williamr@2
    79
         * is loaded.
williamr@2
    80
         */
williamr@2
    81
        IMPORT_C RConeResourceLoader(CCoeEnv& aEnv);
williamr@2
    82
williamr@2
    83
        /**
williamr@2
    84
         * Opens the resource file for reading. Only one resource may be open 
williamr@2
    85
         * at a time. Panics if this instance already has a file open. 
williamr@2
    86
         * The implementation uses BaflUtils::NearestLanguageFile to search 
williamr@2
    87
         * for a localized resource file in proper search order.
williamr@2
    88
         * 
williamr@2
    89
         * @param aFileName is the resource file name to open. This parameter
williamr@2
    90
         * value is changed to the best matching language file found. The drive
williamr@2
    91
         * letter is required in the filename.
williamr@2
    92
         * @return a Symbian OS error code.
williamr@2
    93
         *
williamr@2
    94
         * @panic KErrNotSupported The instance already has a file open.
williamr@2
    95
         */
williamr@2
    96
        IMPORT_C TInt Open(TFileName& aFileName);
williamr@2
    97
williamr@2
    98
        /**
williamr@2
    99
         * Opens the resource file for reading. Only one resource may be open 
williamr@2
   100
         * at a time. Leaves if this instance already has a file open.
williamr@2
   101
         * The implementation uses BaflUtils::NearestLanguageFile to search
williamr@2
   102
         * for a localized resource file in proper search order.
williamr@2
   103
         * 
williamr@2
   104
         * @param aFileName Reference for resource file name. Please
williamr@2
   105
         *                  note that drive letter is required ! 
williamr@2
   106
         *
williamr@2
   107
         * @leave KErrNotSupported The instance already has a file open.
williamr@2
   108
         */
williamr@2
   109
        IMPORT_C void OpenL(TFileName& aFileName);
williamr@2
   110
williamr@2
   111
williamr@2
   112
        /**
williamr@2
   113
         * Closes the opened resource file, if one is open. Does nothing if no
williamr@2
   114
         * file has been opened. New resource file may be opened after the 
williamr@2
   115
         * previous has been closed. Always remember to close the resource when 
williamr@2
   116
         * finished using it.
williamr@2
   117
         */
williamr@2
   118
        IMPORT_C void Close();
williamr@2
   119
williamr@2
   120
    private:
williamr@2
   121
                
williamr@2
   122
        // Prohibit copy constructor and assigment operator because not deriving from CBase.
williamr@2
   123
        RConeResourceLoader(const RConeResourceLoader&);
williamr@2
   124
        RConeResourceLoader& operator= ( const RConeResourceLoader& );
williamr@2
   125
    
williamr@2
   126
        // Needed for closing
williamr@2
   127
        CCoeEnv& iEnv; 
williamr@2
   128
        TInt iResourceFileOffset;
williamr@2
   129
    };
williamr@2
   130
williamr@2
   131
williamr@2
   132
#endif
williamr@2
   133
williamr@2
   134
// End of File