user_guide.html

Delphi 资源文件的使用控件

	<li class="method-params"><em>ResName</em> - the name of the new resource (ordinal 
		or string)</li>
	<li class="method-params"><em>LangID</em> - optional language id of the resource 
		(a language neutral value of 0 is used if this parameter is not provided).</li>
	<li class="method-return">Returns a reference to the new resource entry. This 
		reference should be used to set the resource headers and to store the raw 
		data.</li>
	<li class="method-except">Exception raised if an entry already exists with same 
		type, name and language id.</li>
</ul>
<pre class="method-def"><span class="pascal-kw">function</span> AddEntry(<span class="pascal-kw">const</span> Entry: TPJResourceEntry; <span class="pascal-kw">const</span> ResName: PChar;<span class="pascal-kw">
  const</span> LangID: Word = 0): TPJResourceEntry;</pre>
<p class="method-desc">Adds a copy of the given resource entry to the current 
	&quot;file&quot; object with a new resource name and language id. The new entry 
	has the same resource type as the one being copied.</p>
<ul class="method">
	<li class="method-params"><em>Entry</em> - reference to the resource entry to 
		be copied.</li>
	<li class="method-params"><em>ResName</em> - name of the new resource.</li>
	<li class="method-params"><em>LangID</em> - optional language id of the resource 
		(a language neutral value of 0 is used if this parameter is not provided).</li>
	<li class="method-return">Returns a reference to the new resource entry that 
		has the same header information and data as the one being copied except for 
		resource name and language id.</li>
	<li class="method-except">Exception raised if an entry already exists with same 
		type, name and language id.</li>
</ul>
<pre class="method-def"><span class="pascal-kw">function</span> FindEntry(<span class="pascal-kw">const</span> ResType, ResName: PChar;
  <span class="pascal-kw">const</span> LangID: WORD = $FFFF): TPJResourceEntry;</pre>
<p class="method-desc">Finds a resource entry with the given type, name and language 
	id. The search can ignore the resource name and or language id in which case 
	first entry that matches the provided information is found.</p>
<ul class="method">
	<li class="method-params"><em>ResType</em> - the type of the resource to be 
		found (ordinal or string) - required.</li>
	<li class="method-params"><em>ResName</em> - the name of the resource to be 
		found (ordinal or string). If just the first resource of the given type is 
		required then nil can be specified here.</li>
	<li class="method-params"><em>LangID</em> - the language id of the required 
		resource (optional). If only the first matching resource for the given type 
		and name is required this parameter can be left out (or $FFFF supplied). To 
		find a language neutral resource specify 0 for this parameter.</li>
	<li class="method-return">Returns a reference to the found resource or nil if 
		no resource was found.</li>
</ul>
<pre class="method-def"><span class="pascal-kw">function</span> FindEntryIndex(<span class="pascal-kw">const</span> ResType, ResName: PChar;
  <span class="pascal-kw">const</span> LangID: WORD = $FFFF): Integer;</pre>
<p class="method-desc">Finds the <em>Entries[]</em> property index of a resource 
	entry with the given type, name and language id. The search can ignore resource 
	name or language id in which case first entry that matches the provided information 
	is found.</p>
<ul class="method">
	<li class="method-params"><em>ResType</em> - the type of the resource to be 
		found (ordinal or string) - required.</li>
	<li class="method-params"><em>ResName</em> - the name of the resource to be 
		found (ordinal or string). If just the first resource of the given type is 
		required then nil can be specified here.</li>
	<li class="method-params"><em>LangID</em> - the language id of the required 
		resource (optional). If only the first matching resource for the given type 
		and name is required this parameter can be left out (or $FFFF supplied). To 
		find a language neutral resource specify 0 for this parameter.</li>
	<li class="method-return"> Returns the index of the found resource in the <em>Entries[]</em> 
		property or -1 if no resource was found.</li>
</ul>
<pre class="method-def"><span class="pascal-kw">function</span> EntryExists(<span class="pascal-kw">const</span> ResType, ResName: PChar;
  <span class="pascal-kw">const</span> LangID: WORD = $FFFF): Boolean;</pre>
<p class="method-desc">Checks whether a resource entry matching given search criteria 
	exists.</p>
<ul class="method">
	<li class="method-params"><em>ResType</em> - the type of the resource to be 
		found (ordinal or string) - required.</li>
	<li class="method-params"><em>ResName</em> - the name of the resource to be 
		found (ordinal or string). If just the first resource of the given type is 
		required then nil can be specified here.</li>
	<li class="method-params"><em>LangID</em> - the language id of the required 
		resource (optional). If only the first matching resource for the given type 
		and name is required this parameter can be left out (or $FFFF supplied). To 
		find a language neutral resource specify 0 for this parameter.</li>
	<li class="method-return">Returns true if a resource matching the search criteria 
		exists and false if not. </li>
</ul>
<h5>Properties</h5>
<pre class="method-def"><span class="pascal-kw">property</span> EntryCount: Integer;</pre>
<p class="method-desc">Read-only property that provides the number of resources 
	in the resource file (i.e. the number of entries in the <em>Entries[]</em> property).</p>
<pre class="method-def"><span class="pascal-kw">property</span> Entries[Idx: Integer]: TPJResourceEntry;</pre>
<p class="method-desc">Read-only property that provides access to all the resources 
	in the resource file by index. </p>
<p class="gototop"><a href="#Top">Back to top</a></p>
<h4><a name="TPJResourceEntry"></a>TPJResourceEntry</h4>
<p>Encapsulates a resource within a resource file. Object of this class must not 
	be directly instantiated. <em>TPJResourceFile</em> automatically creates the 
	required objects when they are read from a file or can create new instances 
	in its <em>AddEntry</em> methods. <em>TPJResourceFile</em> is actually an abstract 
	class that provides the required interface for manipulating resource entries. 
	The actual concrete class that implements the resource entry is private. Therefore 
	all valid resource objects are accessed via <em>TPJResourceFile</em>.</p>
<p><em>TPJResourceEntry</em> objects are used to manipulate and interogate resource 
	entries. This is done mainly via properties which give access to resource header 
	information, allow some header information to be set and give read/write access 
	to the raw resource data via a <em>TStream</em>.</p>
<p>Care should be taken not to use a resource entry after the resource file object 
	has been cleared or destroyed or a new resource file has been read since all 
	these actions free previous resource entries. A <em>TPJResourceEntry</em> object 
	can be freed directly - doing so removes the entry from any resource file object 
	it belongs to.</p>
<h5>Methods</h5>
<pre class="method-def"><span class="pascal-kw">function</span> IsMatching(<span class="pascal-kw">const </span>ResType, ResName: PChar;
  <span class="pascal-kw">const</span> LangID: Word = $FFFF): Boolean;</pre>
<p class="method-desc">Checks if the resource entry has the given type, name and 
	language id. The resource name and/or language id can be ignored in which case 
	only the values provided will be matched. For example to match only a resource 
	type use <code>IsMatching(MyResType, nil)</code>;</p>
<ul class="method">
	<li class="method-params"><em>ResType</em> - the resource type (ordinal or string) 
		- required.</li>
	<li class="method-params"><em>ResName</em> - the resource name (ordinal or string) 
		- if nil is passed as this parameter then it is ignored when matching.</li>
	<li class="method-params"><em>LangID</em> - the language id of the resource 
		- if this is left out or $FFFF is passed then it is ingored in the match. 
		To test for a language neutral resource specify 0 in this parameter.</li>
</ul>
<pre class="method-def"><span class="pascal-kw">function</span> IsMatching(<span class="pascal-kw">const</span> Entry: TPJResourceEntry): Boolean;</pre>
<p class="method-desc">Checks if the resource entry has the same type, name and 
	language ID as the given resource entry.</p>
<ul class="method">
	<li class="method-params"><em>Entry</em> - the resource entry to match against.</li>
	<li class="method-return">Returns true if the entries match and false otherwise.</li>
</ul>
<h5>Properties</h5>
<pre class="method-def"><span class="pascal-kw">property</span> DataSize: DWORD;</pre>
<p class="method-desc">Read-only. Provides the size of the resource data (same 
	as calling <em>Data.Size</em>).</p>
<pre class="method-def"><span class="pascal-kw">property</span> HeaderSize: DWORD;</pre>
<p class="method-desc">Read-only. Provides the size of the resource header (which 
	varies depending on the type and size of the resource type and name).</p>
<pre class="method-def"><span class="pascal-kw">property</span> DataVersion: DWORD;</pre>
<p class="method-desc">Gets or sets the predefined data resource version information.</p>
<pre class="method-def"><span class="pascal-kw">property</span> MemoryFlags: Word;</pre>
<p class="method-desc">Gets or sets the attribute bitmask that specifies the state 
	of resource.</p>
<pre class="method-def"><span class="pascal-kw">property</span> LanguageID: Word;</pre>
<p class="method-desc">Read-only. Gets the language used by the resource (value 
	of 0 is language-neutral).</p>
<pre class="method-def"><span class="pascal-kw">property</span> Version: DWORD;</pre>
<p class="method-desc">Gets or sets the user specified version number for resource 
	data.</p>
<pre class="method-def"><span class="pascal-kw">property</span> Characteristics: DWORD;</pre>
<p class="method-desc">Gets or sets the user specified characteristics of the 
	resource.</p>
<pre class="method-def"><span class="pascal-kw">property</span> ResName: PChar;</pre>
<p class="method-desc">Read-only. Gets the name of the resource. This value is 
	either a pointer to a zero-terminated string or an ordinal value as returned 
	from <em>MakeIntResource()</em>.</p>
<pre class="method-def"><span class="pascal-kw">property</span> ResType: PChar;</pre>
<p class="method-desc">Read-only. Gets the type of the resource. This value is 
	either a pointer to a zero-terminated string or an ordinal value as returned 
	from <em>MakeIntResource()</em>.</p>
<pre class="method-def"><span class="pascal-kw">property</span> Data: TStream;</pre>
<p class="method-desc">Read-only. Gets a reference to the stream that contains 
	the resource's raw data. The stream can be used to read or write the data. Any 
	padding bytes that follow the resource's data are not included in the stream. 
</p>
<p class="gototop"><a href="#Top">Back to top</a></p>
<h4><a name="EPJResourceFile"></a>EPJResourceFile</h4>
<p>This is the class of exceptions that are raised directly by <em>TPJResourceFile</em> 
	and <em>TPJResourceEntry</em>. Note that some methods may raise exceptions of 
	other classes.</p>
<p>The class defines no new methods or properties.</p>
<p class="gototop"><a href="#Top">Back to top</a></p>
<h3><a name="Routines"></a>Routines</h3>
<p>The helper routines provided with this code can be used to assist in manipulating 
	resource identifiers. They can be useful for working with Windows API routines 
	as well as the classes presented here. Here are the routines.</p>
<pre class="method-def"><span class="pascal-kw">function</span> IsIntResource(<span class="pascal-kw">const</span> ResID: PChar): Boolean;</pre>
<p class="method-desc">A clone of the IS_<em>INTRESOURCE</em> macro defined on 
	MSDN that checks if a resource identifier is ordinal or a string. Complements 
	the <em>MakeIntResource</em> &quot;macro&quot; defined in <code>Windows.pas</code>.</p>
<ul class="method">
	<li class="method-params"><em>ResID</em> - the resource identifier to check.</li>
	<li class="method-return">Returns true if the indentifier is numeric (as produced 
		by <em>MakeIntResource</em>) or false if it is a pointer to a null terminated 
		string.</li>
</ul>
<pre class="method-def"><span class="pascal-kw">function</span> IsEqualResID(<span class="pascal-kw">const</span> R1, R2: PChar): Boolean;</pre>
<p class="method-desc">Checks for equality of two resource identifiers. To be 
	equal the identifiers either be ordinal and have the same value or must both 
	point to strings that have the same text when case is ignored.</p>
<ul class="method">
	<li class="method-params"><em>R1</em> - the first resource identifier to check.</li>
	<li class="method-params"><em>R2</em> - the second resource identifier to check.</li>
	<li class="method-return">Returns true if the identifiers are equal and false 
		otherwise.</li>
</ul>
<pre class="method-def"><span class="pascal-kw">function</span> ResIDToStr(<span class="pascal-kw">const</span> ResID: PChar): <span class="pascal-kw">string</span>;</pre>
<p class="method-desc">Converts a resource identifier into its string representation 
	as defined on MSDN.</p>
<ul class="method">
	<li class="method-params"><em>ResID</em> - the resource identifier to convert.</li>
	<li class="method-return">Returns the string representation. If the identifier 
		is a string pointer then the string itself is returned. If the identifier 
		is ordinal then the returned string is the integer value preceeded by a # 
		character.</li>
</ul>
<p class="gototop"><a href="#Top">Back to top</a></p>
<h3><a name="Constants"></a>Constants</h3>
<p>Some constants are defined to assist in setting some of the class properties.</p>
<h4>Memory Flags Constants</h4>
<p>The following flags are used to form the bitmask in a resource entry's <em>MemoryFlags</em> 
	property. The first four constants in the table can or ORd together to form 
	the bitmask. The final three constants are complements of the first three and 
	are ANDed againgst the bitmask to remove their complement from the bitmask.</p>
<table border="0" width="100%" cellspacing="1" cellpadding="3" class="bodytableframe">
	<tr> 
		<th width="24%" valign="top">Constant</th>
		<th width="8%" valign="top" align="center">Value</th>
		<th width="68%" valign="top">Description</th>
	</tr>
	<tr class="bodytablebody"> 
		<td width="24%" valign="top"><code>RES_MF_MOVEABLE</code></td>
		<td width="8%" valign="top" align="center"><code>$0010</code></td>
		<td width="68%" valign="top">The system can move the resource in memory. If 
			this flag is not present the resource is fixed in memory.</td>
	</tr>
	<tr class="bodytablebody"> 
		<td width="24%" valign="top"><code>RES_MF_PURE</code></td>
		<td width="8%" valign="top" align="center"><code>$0020</code></td>
		<td width="68%" valign="top">The resource contains DWORD aligned data so that 
			padding is not required. If this flag is not present the resource is not 
			DWORD aligned and must be padded.</td>
	</tr>
	<tr class="bodytablebody"> 
		<td width="24%" valign="top"><code>RES_MF_PRELOAD</code></td>
		<td width="8%" valign="top" align="center"><code>$0040</code></td>
		<td width="68%" valign="top">The resource is to be loaded in memory just after 
			the application itself has been loaded. If not present then loading of the 
			resource may be deferred until required by the application.</td>
	</tr>
	<tr class="bodytablebody"> 
		<td width="24%" valign="top"><code>RES_MF_DISCARDABLE</code></td>
		<td width="8%" valign="top" align="center"><code>$1000</code></td>
		<td width="68%" valign="top">If set then on low memory conditions, the resource 
			can be removed from memory and then reloaded when the application needs 
			it, otherwise the resource must remain in memory.</td>
	</tr>
	<tr class="bodytablebody"> 
		<td width="24%" valign="top"><code>RES_MF_FIXED</code></td>
		<td width="8%" valign="top" align="center"><code>$FFEF</code></td>
		<td width="68%" valign="top">Complement of <code>RES_MF_MOVEABLE</code>: used 
			to remove this flag from the bitmask.</td>
	</tr>
	<tr class="bodytablebody"> 
		<td width="24%" valign="top"><code>RES_MF_IMPURE</code></td>
		<td width="8%" valign="top" align="center"><code>$FFDF</code></td>
		<td width="68%" valign="top">Complement of <code>RES_MF_IMPURE</code>: used 
			to remove this flag from the bitmask.</td>
	</tr>
	<tr class="bodytablebody"> 
		<td width="24%" valign="top"><code>RES_MF_LOADONCALL</code></td>
		<td width="8%" valign="top" align="center"><code>$FFBF</code></td>
		<td width="68%" valign="top">Complement of <code>RES_MF_LOADONCALL</code>: 
			used to remove this flag from the bitmask.</td>
	</tr>
</table>
<p>Note that Windows NT ignores <span class="method-def">RES_MF_MOVEABLE</span>, 
	<span class="method-def">RES_MF_IMPURE</span> and <span class="method-def">RES_MF_PRELOAD</span>.</p>
<h4>Predefined Resource Types</h4>
<p>Delphi's Windows unit defines all the predefined resources types known at the 
	time of writing except <code>RT_HTML</code> and <code>RT_MANIFEST</code>. Therefore 
	these two type identifiers are defined in this unit for convenience:</p>
<blockquote>
	<p><code>RT_HTML = MakeIntResource(23);<br>
		RT_MANIFEST = MakeIntResource(24);</code></p>
</blockquote>