Preparing a Resource Configuration File

Preparing a Resource Configuration File

Both the MUIRCT and the RC Compiler utilities described in Resource Utilities provide a command line option that allows you to specify a resource configuration file for the base language resources. Use of this public, human-readable XML file allows more control over the splitting of resources than can be obtained using the regular command line switches of the utilities. However, even if you do not provide a resource configuration file as an input, the LN and language-specific resource files will contain resource configuration data.

All resource configuration files for Win32 applications begin and end identically:


<?xml version="1.0" encoding="utf-8"?> 
<localization>

<resources>
        
        <!-- a single win32Resources element goes here -->

</resources>
</localization>


This topic focuses on the aspects of the XML schema that are useful in building unmanaged code on Windows Vista and later. In particular, it is only concerned with the behavior of the win32Resources element.

win32Resources Element

The win32Resources element has the attributes described in the following table.

Attribute nameMandatoryDescription
fileTypeNoType of file. Should always be "Application".
checksumNoChecksum value to appear in the resource configuration data of the LN file and language-specific resource files. For example, this attribute allows you to copy the checksum from a single language-specific resource file, by convention the one for English (United States), and place the checksum in a different language-specific resource file. The checksum can be specified as a hexadecimal number string that is no longer than 32 characters. The numerical value must be containable in a 128-bit number.
languageNoLanguage specified using a name format compliant with RFC 4646 (Windows Vista and later), for example, en-US for English (United States).
ultimateFallbackLanguageNoLanguage to insert into the resource configuration data for the LN file, representing the ultimate fallback language to use in a search for a corresponding language-specific resource file. If the resource loader fails to load a requested resource file from the thread preferred UI languages, it uses an ultimate fallback language as its last attempt. The language is specified using a name format compliant with RFC 4646 (Windows Vista and later), for example, en-US for English (United States).
ultimateFallbackLocationNoFallback location. Specify "internal" if ultimate fallback resources are compiled into the LN file. Specify "external" (default) if the LN file is to reference a language-specific resource file for its ultimate fallback resources.

 

In the resource configuration file, the win32Resources element has the sub-elements described in the next table.

Element NameDescription
localizedResourcesResources that encapsulate information about the resource types and individual resources contained in a language-specific resource file.
neutralResourcesResources that encapsulate information about the resource types contained in an LN file.

 

localizedResources Element

Localized resources element. By default, this element has no attributes and only one type of sub-element. It is just a container for resourceType elements.

Attribute NameDescription
resourceTypeType of an individual resource contained in a language-specific resource file.

 

neutralResources Element

Neutral resources element. This element is just a container for resourceType elements.

Attribute NameDescription
resourceTypeType of a single resource contained in an LN file.

 

resourceType Element

The resourceType element encapsulates information about a single resource type or individual resource. It has the attributes listed below.

Caution  Some resource configuration defects are caught only by RC Compiler or MUIRCT, depending on the input resource file or binary file content. The resourceType errors in the resource configuration file that do not exist in the input file are not caught, resulting in unexpected behavior. Users can be using a defective resource configuration file and do not know until they introduce binaries that use the broken parts of the resource configuration file, which creates the appearance that the breaks are from the current binaries.
 
Attribute nameMandatoryDescription
typeNameIdYesType name or identifier for the resource. Specify a string name or a number. If using a number, prepend the string with a "#" to indicate that it represents a number. Each resourceType element must have only one typeNameId attribute.
itemNameNoItem name string for the resource, to be placed in the language-specific resource file. You can specify multiple names, separated by white spaces, for example, "HTML MOFDATA".
itemIdNoIdentifier of individual resource item, to be placed in the language-specific resource file. The item can be specified as a range (for example, "1-12") or by individual identifiers separated by white spaces (for example, "1 3 4").
stringIdNoString identifier for individual resource item, to be placed in the language-specific resource file. The string can be specified as a range (for example, "1-12") or by individual identifiers separated by white spaces (for example, "1 3 4").

This attribute allows the specification of both localizable and nonlocalizable string table entries. It must be used in conjunction with the typeNameId value of "6", denoting a string table entry resource type.

Strings are stored in blocks of 16 in a string table. For example, strings 0 to 15 are stored in a single resource item block and can be referenced in the resource configuration file as itemId 1, or as stringId "0-15". For example, if there are five localizable strings and three nonlocalizable strings, you should assign string identifiers 0-4 for the localizable strings, and string identifiers 16-18 for the nonlocalizable strings. If you do not organize strings this way, the affected blocks of strings are placed in both the LN file and the language-specific resource file.

 

If you specify the itemName, itemId, and/or stringId attributes for a particular resource type under the localizedResource element, only these specified items or strings for the designated resource type are placed in the language-specific resource file. If a resourceType element is specified without any explicit item name, item identifier, or string identifier, all items of the specified resource type are placed in the language-specific resource file. Items or types not listed in any localizedResource element are placed in the LN file.

The following are the standard resource types and their numeric identifiers:

  • CURSOR(1)
  • BITMAP(2)
  • ICON(3)
  • MENU(4)
  • DIALOG(5)
  • STRING(6)
  • FONTDIR(7)
  • FONT(8)
  • ACCELERATORS(9)
  • RCDATA(10)
  • MESSAGETABLE(11)
  • GROUP_CURSOR(12)
  • GROUP_ICON(14)
  • VERSION(16)
  • HTML(23)

Example


<?xml version="1.0" encoding="utf-8"?> 
<localization>
  <resources>
    <win32Resources fileType="Application">
      <neutralResources>
        <resourceType
           typeNameId="#16"
        />
      </neutralResources>
      <localizedResources> 
         <resourceType
                typeNameId="#2"
                itemId="5 6 7 8 9 10 11 12"
                itemName="HTML PRI"
         />
         <resourceType
                typeNameId="#4"
         />
         <resourceType
                typeNameId="#5"
         />
         <resourceType
                typeNameId="#6"
         />
         <resourceType
                typeNameId="#9"
         />
         <resourceType
                typeNameId="#11"
         />
         <resourceType
                typeNameId="#16"
         />
         <resourceType
                typeNameId="HTML"
         />
         <resourceType
                typeNameId="#23"
         />
         <resourceType
                typeNameId="#240"
         />
         <resourceType
                typeNameId="#1024"
         />
         <resourceType
                typeNameId="MY_TYPE"
         />
      </localizedResources> 
    </win32Resources>
  </resources>
</localization>


Related topics

Preparing Resources

 

 

Community Additions

ADD
Show:
© 2016 Microsoft