📄 user_guide.html
字号:
<!--
This file designed to be used either as include file on website for user
guide tab of resfile page OR as stand alone HTML user guide for distribution
with source code.
Simply comment out all sections labelled "for stand-alone file" by removing
closing gt symbol of comment tag. Also comment out appropriate achor tag in
link to articles.php: either local (include file) or remote (HTML doc)
Also need to comment out some of styles for include file version.
Also need to comment out appropriate bullet image references in method-xxx
CSS classes.
-->
<!-- For stand-alone file -->
<html>
<head>
<title>DelphiDabbler.com: PJResFile User Guide</title>
<!-- Common -->
<style type="text/css">
<!--
.method-def {
font-family: "Courier New", Courier, mono;
font-size: 10pt;
margin-bottom: 4px;
}
.method-desc {
margin-left: 24px;
margin-top: 4px;
margin-bottom: 0px;
}
ul.method {
margin-top: 4px;
}
.method-params {
/* For stand-alone file */
list-style-image: url(bullet_p.gif);
/* For include file *
list-style-image: url(/img/sw/resfile-1.gif);
/* Common */
list-style-position: outside;
padding-top: 0px;
padding-bottom: 2px;
margin-left: 24px;
margin-top: 0px;
}
.method-return {
/* For stand-alone file */
list-style-image: url(bullet_r.gif);
/* For include file *
list-style-image: url(/img/sw/resfile-2.gif);
/* Common */
list-style-position: outside;
padding-top: 0px;
padding-bottom: 2px;
margin-left: 24px;
}
.method-except {
/* For stand-alone file */
list-style-image: url(bullet_e.gif);
/* For include file *
list-style-image: url(/img/sw/resfile-3.gif);
/* Common */
list-style-position: outside;
padding-top: 0px;
padding-bottom: 2px;
margin-left: 24px;
}
.gototop {
text-align: center;
border-top: 1px solid #CCCCCC;
border-bottom: 1px solid #CCCCCC;
padding-top: 4px;
padding-bottom: 4px;
}
.pascal-kw {
font-family: "Courier New", Courier, mono;
font-size: 10pt;
font-weight: bold;
}
.pascal-comment {
font-family: "Courier New", Courier, mono;
font-size: 10pt;
color: blue;
}
/* For stand alone file */
body {
background-color : White;
font-family : Verdana, Geneva, Arial, Helvetica, sans-serif;
font-size : 10pt;
}
table {
font-size : 10pt;
}
h1 {
padding-bottom: 4px;
text-align: center;
background-color: #CCCCCC;
border: 1px #999999 solid;
}
h2 {
text-align: center;
padding-bottom: 4px;
border-bottom: 2px #999999 solid;
}
.bodytableframe {
background-color : #CCCCCC;
color : White;
}
.bodytablebody {
background-color : White;
color : Black;
}
/* End */
-->
</style>
<!-- For stand-alone file -->
</head>
<body>
<h1>Resource File Classes<br />by DelphiDabbler</h1>
<h2>User Guide</h2>
<!-- Common -->
<h3><a name="Top"></a>Overview</h3>
<p>These classes support read and writing 32 bit binary resource files. Some routines
are also included that assist in manipulating resource identifiers.</p>
<p>The code encapsulates the high-level structure of a resource file and
its resources. It deals only with raw resource data - the actual format
of the raw data depends on the resource type. This code does not provide
any support for specific resource types or their data formats.</p>
<p>This document is divided into various sections:</p>
<ul class="method">
<li><a href="#Classes">Classes</a> - description of the provided classes
<ul class="method">
<li><a href="#TPJResourceFile">TPJResourceFile</a> - details of usage, methods
and properties of the resource file class</li>
<li><a href="#TPJResourceEntry">TPJResourceEntry</a> - details of usage,
methods and properties of the resource entry class</li>
<li><a href="#EPJResourceFile">EPJResourceFile</a> - description of this
exception class</li>
</ul>
</li>
<li><a href="#Routines">Routines</a> - description of the helper routines</li>
<li><a href="#Constants">Constants</a> - description of constants defined for
use with the classes</li>
<li><a href="#Examples">Examples</a> - examples of using the classes
<ul>
<li><a href="#eg1">#1</a> - Loading a resource file</li>
<li><a href="#eg2">#2</a> - Accessing all resources in a file</li>
<li><a href="#eg3">#3</a> - Finding a resource</li>
<li><a href="#eg4">#4</a> - Listing specific resources from a file</li>
<li><a href="#eg5">#5</a> - Adding or modifying a resource's data</li>
<li><a href="#eg6">#6</a> - Adding a new resources to a file</li>
<li><a href="#eg7">#7</a> - Checking is a resource exists</li>
<li><a href="#eg8">#8</a> - Deleting resources</li>
<li><a href="#eg9">#9</a> - Saving a resource file</li>
<li><a href="#eg10">#10</a> - A practical example</li>
</ul>
</li>
</ul>
<h3><a name="Classes"></a>Classes</h3>
<p>The classes included in this release are as follows:</p>
<table border="0" width="100%" class="bodytableframe" cellspacing="1" cellpadding="3">
<tr>
<th width="17%" valign="top">Class</th>
<th width="83%" valign="top">Description</th>
</tr>
<tr class="bodytablebody">
<td width="17%" valign="top"><em>TPJResourceFile</em></td>
<td width="83%" valign="top">Encapsulates a 32 bit binary resource file and
exposes the entries within it. The class allows resources within the file
to be accessed, created, read and searched for.</td>
</tr>
<tr class="bodytablebody">
<td width="17%" valign="top"><em>TPJResourceEntry</em></td>
<td width="83%" valign="top">Encapsulates a single resource within a resource
file. Permits access to the resource type, name and language. Other header
data can be modified. Provides read/write access to the raw resource data
through a <em>TStream</em>.</td>
</tr>
<tr class="bodytablebody">
<td width="17%" valign="top"><em>EPJResourceFile</em></td>
<td width="83%" valign="top">Class of exception raised by the above classes
to report errors.</td>
</tr>
</table>
<p>Although we use the word "file" in these notes, this term also covers
binary resource data stored in a stream.</p>
<p>Detailed descriptions of the classes now follow.</p>
<h4><a name="TPJResourceFile"></a>TPJResourceFile</h4>
<p>This class is used to encapsulate a 32 bit resource file, to find which resources
in contains and to add new and delete existing resources. The number of resources
in the file is given by the <em>EntryCount</em> property while the <em>Entries[]</em>
property provides access to them. Resource entries are not created directly
by the user but via the <em>AddEntry()</em> method of this class.</p>
<p>Resource entries accessed via this class are <em>TPJResourceEntry</em> objects
and have methods and properties that can be used to interogate and update them.</p>
<h5>Methods</h5>
<pre class="method-def"><span class="pascal-kw">constructor</span> Create;</pre>
<p class="method-desc">Class constructor. Creates a new empty resource file object.</p>
<pre class="method-def"><span class="pascal-kw">destructor</span> Destroy;</pre>
<p class="method-desc">Class destructor. Usually called via the <em>Free</em>
method. Destroying the object frees all the resource entries currently in the
file.</p>
<pre class="method-def"><span class="pascal-kw">procedure</span> Clear;</pre>
<p class="method-params">Clears all resources from the file object. The resources
are freed.</p>
<pre class="method-def"><span class="pascal-kw">function</span> DeleteEntry(<span class="pascal-kw">const</span> Entry: TPJResourceEntry): Boolean;</pre>
<p class="method-desc">Deletes a resource entry from the resource file object
if it exists. The entry object is not freed and must be freed by the user since
it will no longer be freed by the <em>Clear</em> or <em>Destroy</em> methods.
The recommended way to delete and free a resource entry is to free the entry
object since this automatically unlinks it from the resource.</p>
<ul class="method">
<li class="method-params"><em>Entry</em> - reference to resource entry object
to be deleted.</li>
<li class="method-return">Returns true if entry was in the resource list and
was deleted and false otherwise.</li>
</ul>
<pre class="method-def"><span class="pascal-kw">function</span> IndexOfEntry(<span class="pascal-kw">const</span> Entry: TPJResourceEntry): Integer;</pre>
<p class="method-desc">Gets the index number of the given resource entry in the
resource file's <em>Entries[]</em> property.</p>
<ul class="method">
<li class="method-params"><em>Entry</em> - reference to resource entry to be
found.</li>
<li class="method-return">Returns index number if entry was found and -1 if
entry is not in the resource file. </li>
</ul>
<pre class="method-def"><span class="pascal-kw">procedure</span> LoadFromFile(<span class="pascal-kw">const</span> FileName: TFileName);</pre>
<p class="method-desc">Loads a resource file from the named file, replacing any
existing resource.</p>
<ul class="method">
<li class="method-params"><em>FileName</em> - the name of the file from which
to load the resource</li>
<li class="method-except">Exceptions are raised if the file does not exist or
does not contain a valid resource. </li>
</ul>
<pre class="method-def"><span class="pascal-kw">procedure</span> LoadFromStream(<span class="pascal-kw">const</span> Stm: TStream);</pre>
<p class="method-desc">Loads a resource "file" from the current location
in the given stream.</p>
<ul class="method">
<li class="method-params"><em>Stm</em> - the stream from which to load the resource</li>
<li class="method-except">Exceptions are raised if the stream does not contain
a valid resource file. </li>
</ul>
<pre class="method-def"><span class="pascal-kw">procedure</span> SaveToFile(<span class="pascal-kw">const</span> FileName: TFileName);</pre>
<p class="method-desc">Saves data as a 32 bit resource file.</p>
<ul class="method">
<li class="method-params"><em>FileName</em> - the name of the file.</li>
<li class="method-except">Exceptions are raised if the file cannot be created.</li>
</ul>
<pre class="method-def"><span class="pascal-kw">procedure</span> SaveToStream(<span class="pascal-kw">const</span> Stm: TStream);</pre>
<p class="method-desc">Saves data in resource file format on the given stream
at the current location.</p>
<ul class="method">
<li class="method-except">Exceptions are raised if the stream does not support
writing.</li>
</ul>
<pre class="method-def"><span class="pascal-kw">class function</span> IsValidResourceStream(<span class="pascal-kw">const</span> Stm: TStream): Boolean;</pre>
<p class="method-desc">Checks if the given stream contains data representing a
valid 32 bit resource file starting at the current location. This method checks
that a 32 bit resource file header is present but does not validate the whole
of the file. Note that the stream is not rewound to the starting position after
the check is made.</p>
<ul class="method">
<li class="method-params"><em>Stm</em> - the stream containing the resource
file.</li>
</ul>
<pre class="method-def"><span class="pascal-kw">function</span> AddEntry(<span class="pascal-kw">const</span> ResType, ResName: PChar;<span class="pascal-kw">
const</span> LangID: Word = 0): TPJResourceEntry;</pre>
<p class="method-desc">Adds a new, empty, resource to the current "file"
object.</p>
<ul class="method">
<li class="method-params"><em>ResType</em> - the type of the new resource (ordinal
or string).</li>
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -