Main Page   Namespace List   Class Hierarchy   Compound List   File List   Namespace Members   Compound Members   File Members  

ZResource.h

Go to the documentation of this file.
00001 
00002 //-------------------------------------------------------------------------------------------------
00003 //                                                                        
00004 //   Module Name: ZResource.h
00005 //
00006 //   General Description: classes to use and create resource files
00007 //
00008 //-------------------------------------------------------------------------------------------------
00009 //
00010 //                            Motorola Confidential Proprietary
00011 //                     Template ID and version: TMP_LFC_50068  Version 1.2
00012 //                      (c) Copyright Motorola 200{x}, All Rights Reserved
00013 //
00014 //-------------------------------------------------------------------------------------------------
00015 
00016 #ifndef Z_RESOURCE_H
00017 #define Z_RESOURCE_H
00018 
00019 #ifndef __cplusplus
00020 #error "This is a C++ header file; it requires C++ to compile."
00021 #endif
00022 
00023 #include <qstring.h>
00024 #include <qpixmap.h>
00025 #include <qarray.h>
00026 #include <qsortedlist.h>
00027 
00028 
00029 class QFile;
00030 class ZResEntry;
00031 struct ZResHTEntry;
00032 struct ZResStartBlock;
00033 
00034 
00035 /**
00036  * Base class for resource readers.  A resource reader is used to get icons
00037  * and other resources.  Most of the methods of this class are not implemented.
00038  */
00039 
00040 class ZResReader {
00041 
00042 public:
00043 
00044     /**
00045      * virtual distructor.  Derived classes should reimplement if they have
00046      * cleanup to do.
00047      */
00048     virtual ~ZResReader();
00049    
00050     /**
00051      * return bool indicating whether or not a resource exists
00052      *
00053      * @param ID resource ID to lookup (something.g for a graphic, for example)
00054      * @return bool indicating whether or not the resource exists
00055      *
00056      */
00057     virtual bool exists(const QString& ID) const = 0;
00058 
00059     /**
00060      * get data for a resource.
00061      *
00062      * @param ID the resource ID for the resource
00063      * @param ppOutData out-pointer for the resource data
00064      * @param pOutLength out-integer for the size in bytes of the data
00065      * 
00066      * @note Do not delete/de-allocate the pointer returned from this function.
00067      *
00068      */
00069     virtual bool get(const QString& ID, unsigned char** ppOutData, 
00070                      int* pOutLength) const = 0;
00071 
00072     /**
00073      * get the first resource ID in this resource reader
00074      *
00075      * @note this function is not thread safe
00076      * @return first resource ID
00077      */
00078     virtual QString getFirstID();
00079 
00080     /**
00081      * get the next resource ID in this resource reader
00082      *
00083      * @note this function in not thread safe
00084      * @return current resource ID, increments iterator
00085      */
00086     virtual QString getNextID();
00087 
00088 };
00089 
00090 //----------------------------------------------------------------------------
00091 //                            CLASS ZResFileReader
00092 //----------------------------------------------------------------------------
00093 
00094 /**
00095  * class to read resource files written by a ZResFileWriter
00096  *
00097  * Use ZResFileReader to read QPixmaps or other data from a single resource
00098  * file.  If you want to use the current application skin (which is made of
00099  * a number of resource files, see ZSkin.
00100  * 
00101  * @note you can see what resources are in a resource file by opening the
00102  * file with a text editor.  The beginning of the file contains an easily
00103  * readable list of resource names.
00104  *
00105  */
00106 
00107 class ZResFileReader : public ZResReader
00108 {
00109 public:
00110 
00111     /**
00112      * default constructor
00113      */
00114     ZResFileReader();
00115 
00116     /**
00117      * constructor taking a file name as an argument
00118      */
00119     ZResFileReader(const QString& fileName);
00120 
00121 
00122     /**
00123      * destructor
00124      */
00125     virtual ~ZResFileReader();
00126 
00127     /**
00128      * sets the filename for this resource reader.  This causes any previously
00129      * opened resource file to be closed. 
00130      *
00131      * @param fileName the filename to open
00132      * @return true if the file was successfully openend, false otherwise
00133      *
00134      * @note any pointers returned from this object before calling this function
00135      * should be considered invalid
00136      */
00137     bool setFileName(const QString& fileName);
00138 
00139     /**
00140      * return the filename used by this resource reader
00141      */
00142     const QString& fileName() const;
00143 
00144     /**
00145      * return a value indicating whether or not a given string ID exists
00146      *
00147      * @return bool indicating whether or not a resource exists
00148      */
00149     virtual bool exists(const QString& ID) const;
00150     
00151     /**
00152      * get data for a resource.
00153      *
00154      * @param ID the resource ID for the resource
00155      * @param ppOutData out-pointer for the resource data
00156      * @param pOutLength out-integer for the size in bytes of the data
00157      * 
00158      * @note Do not delete/de-allocate the pointer returned from this function.
00159      *
00160      */
00161     virtual bool get(const QString& ID, unsigned char** ppOutData, 
00162                      int* pOutLength) const;
00163 
00164     /**
00165      * get the first resource ID in this resource reader
00166      *
00167      * @note this function is not thread safe
00168      * @return first resource ID
00169      */
00170     virtual QString getFirstID();
00171 
00172     /**
00173      * get the next resource ID in this resource reader
00174      *
00175      * @note this function in not thread safe
00176      * @return current resource ID, increments iterator
00177      */
00178     virtual QString getNextID();
00179 
00180 
00181 protected:
00182 
00183     /**
00184      * init is called by the constructors
00185      */
00186     void init(const QString& fileName);
00187 
00188     /**
00189      * reset resets the object state
00190      */
00191     void reset();
00192 
00193     /**
00194      * load actually loads the resource table
00195      */
00196     bool bLoadFailed;
00197     bool load();
00198 
00199     /**
00200      * getID return the resource ID for a given hash table
00201      * entry number
00202      */
00203     QString getID(unsigned hashTableEntryNum) const;
00204 
00205     /**
00206      * returns a pointer to a hashTableEntry for a given ID
00207      */
00208     const ZResHTEntry *getHashTableEntry(const QString& ID) const;
00209 
00210     /**
00211      * returns a pointer to the data at a given file offset
00212      * returns false if an error occurs.
00213      */
00214     bool getDataAtOffset(unsigned offset, 
00215                          unsigned char **ppOutData, 
00216                          int *pOutLength) const;
00217 
00218     bool getDataAtOffset(unsigned offset, 
00219                          QString& resourceFileName, 
00220                          unsigned char **ppOutData, 
00221                          int *pOutLength) const;
00222    
00223     QString m_fileName;   ///< the name of the resource file
00224 
00225     bool loaded;
00226     int fd;
00227     unsigned int fileLength;
00228     unsigned char *pResources;
00229 
00230     unsigned char *pIDs;
00231     unsigned hashTableSize;
00232     ZResHTEntry *pHashTable;
00233     unsigned char *pData;
00234     unsigned char *pEnd;
00235 
00236     unsigned currentIteratorEntry;
00237 
00238 };
00239 
00240 
00241 /**
00242  * class to create a resource file
00243  */
00244 
00245 class ZResFileWriter {
00246 
00247 public:
00248 
00249     /**
00250      * constructor
00251      */
00252 
00253     ZResFileWriter();
00254 
00255     /**
00256      * constructor taking an output file name
00257      */
00258 
00259     ZResFileWriter(const QString& fileName);
00260 
00261     /**
00262      * set the output filename
00263      *
00264      * @param fileName name of the file to write
00265      */
00266 
00267     void setFileName(const QString& fileName);
00268 
00269     /**
00270      * get the current filename being written to
00271      *
00272      * @return reference to the filename being written to
00273      */
00274 
00275     const QString& fileName() const;
00276 
00277     /**
00278      * throw away all data and start at the beginning
00279      */
00280 
00281     void reset();
00282 
00283     /**
00284      * add a block of data to the resource file
00285      *
00286      * @param ID resource ID of data to add
00287      * @param data QByteArray of the data to add
00288      */
00289 
00290     void add(const QString& ID, const QByteArray& data);
00291 
00292     /**
00293      * write the resource file
00294      *
00295      * @return true if write succeeded
00296      */
00297 
00298     bool write();
00299 
00300 protected:
00301 
00302     void init(const QString& fullFileName);
00303 
00304     QString m_fileName;  ///<  file name that we're writing to
00305 
00306     bool createTables();
00307     bool writeHeader(QFile&);
00308     bool writeIDs(QFile&);
00309     bool writeStartBlock(QFile&);
00310     bool writeHashTable(QFile&);
00311     bool writeData(QFile&);
00312     bool deleteTables();
00313 
00314     QSortedList<ZResEntry> list;   ///< list of resources before they're written to disk
00315 
00316     unsigned int hashTableSize;
00317     ZResHTEntry *hashTable;
00318     bool hash(const QString& ID, const QByteArray& inData);
00319 
00320     int nextLabelOffset;
00321     int nextDataOffset;
00322 };
00323 
00324 #endif // Z_RESOURCE_H

Generated at Wed Mar 3 13:22:02 2004 by doxygen1.2.8.1 written by Dimitri van Heesch, © 1997-2001