Public Member Functions | |
FSFile | FindResourceFile (string resourceName) |
This is the main service of instances: Return a stream on the resource described by a local path name representation. | |
override string | ToString () |
Static Public Member Functions | |
static void | AddCatalogLookupPrefix (string prefix) |
static Stream | FindResource (string archiveName, string resourceName, string canonicalName) |
static Stream | FindResource (string archiveName, string resourceName) |
static Stream | FindResource (Assembly callingAssembly, string archiveName, string resourceName) |
static FSFile | FindResourceFile (string archiveName, string resourceName, string canonicalName) |
static FSFile | FindResourceFile (string archiveName, string resourceName) |
static string[] | GetDerivatedArchiveNames (string archiveName, string canonicalName) |
static string[] | GetDerivatedArchiveNames (string archiveName) |
static string[] | GetDerivatedResourceNames (string resourceName, string canonicalName) |
static string[] | GetDerivatedResourceNames (string archiveName) |
static FSFile | ResourceFileAppropriateType (string archiveName, string resourceName) |
static FSFile | ResourceFileCanSeek (string archiveName, string resourceName) |
Properties | |
bool | IsArchive [get] |
If this is an archive. | |
bool | IsDir [get] |
If this is a directory. | |
bool | IsEmpty [get] |
Archive has not been found. | |
static ZipResource | LastFoundArchive [get] |
static string | LastFoundArchiveName [get] |
static string | LastFoundResourceName [get] |
static string | LastSearchedArchiveName [get] |
Classes | |
class | KeyArchiveName |
Refer also to ZipRC as help file compiler.
C# has a nice native resource system that only has two drawbacks: Support for internationalization is less productive than the classical gettext procedure and the visual development environment supports things like images as resources only within Forms.
This class is meant as a very simple alternative. It cannot be used to retrieve resources that have been linked into the application itself but it can serve as a replacement for satellite assemblies.
Call FindResource() or FindResourceFile() to get a stream or a FSFile descriptor for accessing the content of a resource. These resource may either be simply files within a certain directory, zipped directories, or resources embedded into the manufest.
Resources may be stored in different types of streams, either ZIP files, System.IO file streams, or memory streams. Unfortunately, these types of streams differ with respect to some characteristics that are used within wxWidgets. Namely, especially the image handler presuppose streams as data source that can seek. ZipResource is prepared to deal with this if you use the methods ResourceFileCanSeek() and ResourceFileAppropriateType(). Refer to the remarks on these methods for details. ResourceFileAppropriateType() forms the basis of the zrs
:// file system protocol according to IOStreamFSHandler.
This class maintains a collection of archive files resp. instances of ArchiveEntry that will be used for loading resources. Users of the class provide a resource name an archive name. If not already analysed, the archive will be loaded and a stream on the resource contents will be returned. Refer to FindResource() for details. The main service of this class is to amend names of resources and archives with the canonical name of the current locale. So, this class enables locale specific provision of resources.
Resource archives will be found in the codebase path of the calling assembly, subdirectory "zrs" or a subdirectory named with the canonical name of the current locale.
You may also use directories instead of archives.
Whenever a resource cannot be found in files, the manifest will be searched.
What is loaded: A resource will be loaded on FindResource(archiveName, resourceName)
or FindResource(archiveName, resourceName, canonicalLocaleName)
, where
archiveName
is a filename of the archive resourceName
is the (local/native, not internal) filename of the resource, and canonicalLocateName
is something like "en", "en_UK", or "de_DE".csc.exe
option /resource)
and then from the local file system.A missing locale name will be loaded from wx.Locale.
The method does not directly search for provided filenames for archive and resource but produce derivated filenames for both using the canonical name of the locale as a parameter. Possible locations of the archive also reflect prefixes as added by method AddCatalogLookupPrefix(). The code base directory of the calling assembly will also be considered as a prefix path.
For each prefix, a file directory/archive.zrs
for locale "de_DE" will be loaded as one of the following files (referring to the order as given below):
/prefix/zrs/de_DE/directory/archive_de_DE.zrs
/prefix/zrs/directory/archive_de_DE.zrs
/prefix/zrs/de_DE/directory/archive.zrs
/prefix/de_DE/directory/archive_de_DE.zrs
/prefix/directory/archive_de_DE.zrs
/prefix/de_DE/directory/archive.zrs
/prefix/zrs/de/directory/archive_de.zrs
/prefix/zrs/directory/archive_de.zrs
/prefix/zrs/de/directory/archive.zrs
/prefix/de/directory/archive_de.zrs
/prefix/directory/archive_de.zrs
/prefix/de/directory/archive.zrs
/prefix/directory/archive.zrs
/prefix/zrs/directory/archive.zrs
FindResource(archiveName, resourceName, "")
) only these two path names will be searched.The locale can ne specified within the path as well as within the filename. The latter form may be used to avoid the effect that the usage of a particular file (as a localized resource) depends only on its position in the directory tree.
Directory name zrs
is used as a standard amendment to the prefix. Reason: Usually, the code base of the calling assembly will be the only prefix. This is typically a Bin
directory already crowded with lots of files required on running the program. A system designer may use a sub-directory zrs
without any changes to the code to prevent the files on resources to additionally appear directly in this directory.
Note, that each resource archive may also contain the same resource in several localizations, because also a resourceName
like "rdirectory/resource" is used to produce derivations.
de_DE/rdirectory/resource
rdirectory/de_DE/resource
de_DE/rdirectory/resource_de_DE
rdirectory/de_DE/resource_de_DE
de/rdirectory/resource
rdirectory/de/resource
de/rdirectory/resource_de
rdirectory/de_DE/resource_de
rdirectory/resource
directory/archive.zrs
in file entry rdirectory/en/resource
. The Germen localization may be shipped as another file resource_de.zrs
containing entry rdirectory/resource
. Both resources will be found although the English version of the resource has been added to the neutral archive whereas the German version is in a perticularly localized archive.
A ZipResource file may be compiled and analyzed by program ZipRC.exe
(refer to directory Utils)
. Call ZipRC.exe
-h
on a CMD.exe console to get information on using this program.
C:\\wx.NET\\Bin> ZipRC.exe -h ZipRC 0.7.3 (c) 2006 wx.NET Team Generate ZIP archived resources .zrs. Synopsis: ZipRC.exe (compile | c | extract | e | verify | v) ARCHIVE_FILE {--help | -h | --CANONICAL_NAME | FILE | RCNAME=FILE}* compile/c: Compile archive file ARCHIVE_FILE extract/e: Extract files from ARCHIVE_FILE info/i: Information ARCHIVE_FILE and the specified files (search paths, comparison) --help/-h: PrintData this information. --CANONCAL_NAME e.g. --en|--de_DE: switch to the specified locale. FILE: compile or extract this file. RCFILE=FILE: compile FILE as RCFILE or extract RCFILE to FILE.
Example: The current working directory contains the files logo2.png
, editDocGroups.html
, and editDocGroups_de.html
where the last file is a German translation of the second one whereas the icon logo2.png
is neutral (with repsect to localization).
ZipRC c test.zip wxnetlogo.png=logo2.png editDocGroups.html --de editDocGroups_de.html
test.zip
. This archive contains wxnetlogo.png
(a copy of the original file logo2.png)
and editDocGroups.html
in its root and editDocGroups_de.html
in sub-directory de
. This is to indicate that the latter HTML file is a German translation whereas the other files are considered neutral with respect to localization.
The more interesting thing about ZipResource is of course reading the resource. The application knows command extract
to decompress the content. However, the application also knows command verify
to investigate the structure of a compiled archive and compare the content with uncompressed files (for instance the original sources). Back to the example:
ZipRC v test.zip wxnetlogo.png=logo2.png editDocGroups.html --de editDocGroups_de.html
ZipRC 0.7.3 (c) 2006 wx.NET Team 1/4: Candidate test.zip existing as file containing: 1: "wxnetlogo.png"<=>"wxnetlogo.png" 28.10.2006 19:18:54 size 5215 2: "editDocGroups.html"<=>"editDocGroups.html" 28.10.2006 19:18:54 size 548 3: "de/editDocGroups_de.html"<=>"deditDocGroups_de.html" 28.10.2006 19:18:54 size 727 2/4: Candidate zrs\test.zip is unknown. 3/4: Candidate file:\C:\sf\wx.NET\Bin\test.zip is unknown. 4/4: Candidate file:\C:\sf\wx.NET\Bin\zrs\test.zip is unknown.
test.zip
matches with archive file test.zip
containing the listed files (with their local and internal names). The program has not been able to find archives corresponding to the rest of the derivated file names. Looking for resource wxnetlogo.png <=> file logo2.png, locale neutral in test.zip. Derivations of the resource name: 1. wxnetlogo.png Found in test.zip as wxnetlogo.png Both files share the same content.
logo2.png
has been found on the file system and has been successfully compared to wxnetlogo.png
from the archive. Looking for resource editDocGroups.html <=> file editDocGroups.html, locale neutral in test.zip. Derivations of the resource name: 1. editDocGroups.html Found in test.zip as editDocGroups.html Both files share the same content.
editDocGroups.html
has also been found and compared. Archive test.zip will be searched with locale <de> as: 1/16: 1. file:\C:\sf\wx.NET\Bin\de\test.zip has not been found. 2/16: 2. file:\C:\sf\wx.NET\Bin\zrs\test_de.zip has not been found. 3/16: 3. file:\C:\sf\wx.NET\Bin\zrs\de\test.zip has not been found. 4/16: 4. file:\C:\sf\wx.NET\Bin\zrs\de\test_de.zip has not been found. 5/16: 5. zrs\test_de.zip has not been found. 6/16: 6. test_de.zip has not been found. 7/16: 7. de\test_de.zip has not been found. 8/16: 8. zrs\de\test_de.zip has not been found. 9/16: 9. file:\C:\sf\wx.NET\Bin\test_de.zip has not been found. 10/16: 10. zrs\de\test.zip has not been found. 11/16: 11. de\test.zip has not been found. 12/16: 12. file:\C:\sf\wx.NET\Bin\de\test_de.zip has not been found. 13/16: 13. test.zip is an existing file containing: 1: "wxnetlogo.png"<=>"wxnetlogo.png" 28.10.2006 19:18:54 size 5215 2: "editDocGroups.html"<=>"editDocGroups.html" 28.10.2006 19:18:54 size 548 3: "de/editDocGroups_de.html"<=>"deditDocGroups_de.html" 28.10.2006 19:18:54 size 727 14/16: 14. zrs\test.zip has not been found. 15/16: 15. file:\C:\sf\wx.NET\Bin\test.zip has not been found. 16/16: 16. file:\C:\sf\wx.NET\Bin\zrs\test.zip has not been found.
de
. The program lists all derivated file names of test.zip
and the contents of the archives found on the file system. Looking for resource editDocGroups_de.html <=> file editDocGroups_de.html, local e de in test.zip. Derivations of the resource name: 1. editDocGroups_de.html 2. \deditDocGroups_de.html Found in test.zip as \deditDocGroups_de.html Both files share the same content.
editDocGroups_de.html
are listed. One of these derivations .htmlcan be found in
test.zip
. Both files have the same content.
Note, that also directories can be treated as resources. Compiled resources are important for deployment, not development. So, class ZipResource
treats directories the same way as archive files. Reconsider the verifier of program ZipRC
. This time we will call this directly with the working directory as archived source.
ZipRC v . wxnetlogo.png=logo2.png editDocGroups.html --de editDocGroups_de.html
ZipRC 0.7.3 (c) 2006 wx.NET Team 1/8: Candidate . exists as directory. 2/8: Candidate zrs\.zrs is unknown. 3/8: Candidate .zrs is unknown. 4/8: Candidate file:\C:\sf\wx.NET\Bin\ is unknown. 5/8: Candidate zrs\ is unknown. 6/8: Candidate file:\C:\sf\wx.NET\Bin\.zrs is unknown. 7/8: Candidate file:\C:\sf\wx.NET\Bin\zrs\.zrs is unknown. 8/8: Candidate file:\C:\sf\wx.NET\Bin\zrs\ is unknown. Looking for resource wxnetlogo.png <=> file <logo2.png>, locale neutral in <.>. Derivations of the resource name: 1. wxnetlogo.png Cannot open resource <wxnetlogo.png> in <.>.
"."
to denote a directory. The command line specified that source logo2.png
has been renamed to wxnetlogo.png
in the resource file. However, since "."
is exactly the directory of the sources, logo2.png
appears here with its original name so wxnetlogo.png
cannot be found. Looking for resource editDocGroups.html <=> file <editDocGroups.html>, locale neutral in <.>. Derivations of the resource name: 1. editDocGroups.html Found in <.> as <editDocGroups.html> Directory as resource and reference refer to the same file C:\sf\wx.NET\Utils\Zi pRCditDocGroups.html.
editdocGroups.html
since the command line didn't specify a renaming scheme here. Archive . will be searched with locale <de> as: 1/32: 1. file:\C:\sf\wx.NET\Bin\de\.zrs has not been found. 2/32: 2. zrs\de\_de.zrs has not been found. 3/32: 3. file:\C:\sf\wx.NET\Bin\zrs\de\.zrs has not been found. 4/32: 4. file:\C:\sf\wx.NET\Bin\de\_de has not been found. 5/32: 5. file:\C:\sf\wx.NET\Bin\zrs\_de.zrs has not been found. 6/32: 6. zrs\_de.zrs has not been found. 7/32: 7. file:\C:\sf\wx.NET\Bin\zrs\_de has not been found. 8/32: 8. de\_de has not been found. 9/32: 9. zrs\de\.zrs has not been found. 10/32: 10. zrs\_de has not been found. 11/32: 11. zrs\de\_de has not been found. 12/32: 12. file:\C:\sf\wx.NET\Bin\de\_de.zrs has not been found. 13/32: 13. file:\C:\sf\wx.NET\Bin\_de.zrs has not been found. 14/32: 14. file:\C:\sf\wx.NET\Bin\zrs\de\ has not been found. 15/32: 15. file:\C:\sf\wx.NET\Bin\de\ has not been found. 16/32: 16. de\.zrs has not been found. 17/32: 17. zrs\de\ has not been found. 18/32: 18. file:\C:\sf\wx.NET\Bin\zrs\de\_de has not been found. 19/32: 19. _de has not been found. 20/32: 20. de\_de.zrs has not been found. 21/32: 21. _de.zrs has not been found. 22/32: 22. file:\C:\sf\wx.NET\Bin\_de has not been found. 23/32: 23. de\ has not been found. 24/32: 24. file:\C:\sf\wx.NET\Bin\zrs\de\_de.zrs has not been found. 25/32: 25. . is an existing directory. 26/32: 26. zrs\.zrs has not been found. 27/32: 27. .zrs has not been found. 28/32: 28. file:\C:\sf\wx.NET\Bin\ has not been found. 29/32: 29. zrs\ has not been found. 30/32: 30. file:\C:\sf\wx.NET\Bin\.zrs has not been found. 31/32: 31. file:\C:\sf\wx.NET\Bin\zrs\.zrs has not been found. 32/32: 32. file:\C:\sf\wx.NET\Bin\zrs\ has not been found. Looking for resource editDocGroups_de.html <=> file <editDocGroups_de.html>, loc ale de in <.>. Derivations of the resource name: 1. editDocGroups_de.html 2. editDocGroups_de.html Found in <.> as <editDocGroups_de.html> Directory as resource and reference refer to the same file C:\sf\wx.NET\Utils\Zi pRCditDocGroups_de.html.
de
whereas "."
is of a flat structure.
Motivation: Assume you develop an application "app.exe"
involving several resource. During development you want direct access to these resources in order to modify them. So, you will probably check in a subdirectory app
(or another name) containing all resources. However, you will use ZipRC
to compile file "app.zrs"
containing all resources. This file will be shiped with the executable code. The interesting thing is, that both configurations of resources can be accessd by the same program code using ZipResource.
static void wx.Archive.ZipResource.AddCatalogLookupPrefix | ( | string | prefix | ) | [static] |
Add a prefix to be lookup path for loading archives with resources. Similar to wx.Locale.AddCatalogLookupPrefix(). The message catalog files will be looked up under prefix/LANG/zrs
, prefix/LANG
, and prefix
(in this order) where LANG is the canonical name of a locale.
prefix
will be expanded using the code base path of the calling assembly if necessary. So, the meaning of prefix
never relies on the CWD but always on the position of the assemblies.
This only applies to subsequent instance creations.
static Stream wx.Archive.ZipResource.FindResource | ( | string | archiveName, | |
string | resourceName, | |||
string | canonicalName | |||
) | [static] |
Finds a stream containing a resource of the provided name suitable for the specified locale from the provided archive.
archiveName | is a filename describing the archive where the resource has been compiled in. This may also be the name of a resource. This method will generate derivates from this name as described below. | |
resourceName | is a native filename (according to the conventions of class Path) describing the resource. This method will generate derivates from this name as described below. | |
canonicalName | is the canonical name of the locale that the required resource has to comply with. If a locale specific resource cannot be found, the method will load a neutral version. If this is null or empty, this method will immediately search for a neutral resource. |
This method will return a null
if the desired resource cannot be find.
static Stream wx.Archive.ZipResource.FindResource | ( | string | archiveName, | |
string | resourceName | |||
) | [static] |
Finds a stream containing a resource of the provided name from the provided archive. Refer to FindResource(string, string, string) for details.
Non-rooted paths will be rooted with reference to the code base of the calling assembly.
static Stream wx.Archive.ZipResource.FindResource | ( | Assembly | callingAssembly, | |
string | archiveName, | |||
string | resourceName | |||
) | [static] |
Finds a stream containing a resource of the provided name from the provided archive. Refer to FindResource(string, string, string) for details.
Non-rooted paths will be rooted with reference to the code base of callingAssembly
.
static FSFile wx.Archive.ZipResource.FindResourceFile | ( | string | archiveName, | |
string | resourceName, | |||
string | canonicalName | |||
) | [static] |
Finds a FSFile instance containing a resource of the provided name from the provided archive of a provided locale (culture). Refer to FindResource(string, string, string) for details.
static FSFile wx.Archive.ZipResource.FindResourceFile | ( | string | archiveName, | |
string | resourceName | |||
) | [static] |
Finds a FSFile instance containing a resource of the provided name from the provided archive. Refer to FindResource(string, string, string) for details.
FSFile wx.Archive.ZipResource.FindResourceFile | ( | string | resourceName | ) |
This is the main service of instances: Return a stream on the resource described by a local path name representation.
Result is null
if nothing has been found.
static string [] wx.Archive.ZipResource.GetDerivatedArchiveNames | ( | string | archiveName, | |
string | canonicalName | |||
) | [static] |
Returns the file names derivated from archiveName
assuming the locale canonicalName
. Use the empty string to denote the neutral locale.
static string [] wx.Archive.ZipResource.GetDerivatedArchiveNames | ( | string | archiveName | ) | [static] |
Returns the file names derivated from archiveName
of the current wx.Locale
.
static string [] wx.Archive.ZipResource.GetDerivatedResourceNames | ( | string | resourceName, | |
string | canonicalName | |||
) | [static] |
Returns the resource names derivated from resourceName
assuming locale canonicalName
. Use the empty string to denote the neutral locale.
static string [] wx.Archive.ZipResource.GetDerivatedResourceNames | ( | string | archiveName | ) | [static] |
Returns the resource names derivated from resourceName
of the current wx.Locale
.
static FSFile wx.Archive.ZipResource.ResourceFileAppropriateType | ( | string | archiveName, | |
string | resourceName | |||
) | [static] |
This method will produce a stream that can seek (cf. ResourceFileCanSeek) if this seems to be appropriate referring to the mime type. At least images need streams as data source that can seek. This method will call ResourceFile() and analyze the mime type of the result. If considered to be appropriate, the content of the resource stream will be copied into a System.IO.MemoryStream in order to get a stream that can seek positions. Refer also to ResourceFileCanSeek().
static FSFile wx.Archive.ZipResource.ResourceFileCanSeek | ( | string | archiveName, | |
string | resourceName | |||
) | [static] |
Some kinds of data, especially images, require data sources that can seek positions in the stream. This will call ResourceFile() and then, if the result cannot seek, load the source directly into a memory stream.
override string wx.Archive.ZipResource.ToString | ( | ) |
bool wx.Archive.ZipResource.IsArchive [get] |
If this is an archive.
bool wx.Archive.ZipResource.IsDir [get] |
If this is a directory.
bool wx.Archive.ZipResource.IsEmpty [get] |
Archive has not been found.
ZipResource wx.Archive.ZipResource.LastFoundArchive [static, get] |
The last ZipResource found by FindResource().
string wx.Archive.ZipResource.LastFoundArchiveName [static, get] |
The last name of a resource that has been found by FindResource(). This may be null
.
string wx.Archive.ZipResource.LastFoundResourceName [static, get] |
The last name of a resource that has been found by FindResource(). This may be null
.
string wx.Archive.ZipResource.LastSearchedArchiveName [static, get] |
The last name of a resource that has been tried to be loaded by FindResource(). This may be null
.