General comments
The purpose of this interface is to enable associating a name with an icon and allow client programs to obtain an IconFlavor for the corresponding icon without having to worry about which file the actual definition of the icon is stored in (and which icon index in that file). Furthermore, a cache is kept of the iconflavors that have already been created, so that the client can simply call DBIcons.GetIcon each place that the corresponding icon flavor is desired without having to distinguish the first call from subsequent calls.
Icons can be registered from programs via the procedure RegisterIcon; these changes are permanently stored in the current icon database. Additionally, the ReadCatalogue procedure can be called to load a collection of icon definitions into the database; the stream that is read is assumed to be a vanilla text file with lines of the form
iconName: fileName index
where fileName can be a full path name. WriteCatalogue appends entries to the given stream that can be read back in with ReadCatalogue.
Procedures
EstablishIconDB:
PROC [file: Rope.
ROPE];
Establishes the file named in the argument as the current icon database
IconDB:
READONLY Rope.
ROPE;
The name of the current icon database
readOnly:
READONLY
BOOLEAN;
Whether the current database can be written on or not
RegisterIcon:
PROC [iconName: Rope.
ROPE, fileName: Rope.
ROPE, index:
CARDINAL];
Registers the indicated icon. The new registration replaces an earlier registration, if any. Note that the icon Flavor itself is not actually created until the icon is used, i.e. until GetIcon is called. RegisterIcon does not check for existence of fileName, or validity of index.
If saveInCatalogue is TRUE, and this registration constitutes a change, i.e. new iconName, or different fileName or index, rewrites RegisteredIcons.Catalogue to reflect the indicated association.
IsRegistered:
PROC[iconName: Rope.
ROPE ←
NIL, fileName: Rope.
ROPE ←
NIL, index:
CARDINAL ←
LAST[
CARDINAL]]
RETURNS[name: Rope.
ROPE, file: Rope.
ROPE, i:
CARDINAL];
Can be called with either iconName, or fileName and index. name = NIL if not registered.
GetIcon:
PROC [iconName: Rope.
ROPE, default: Icons.IconFlavor ← unInit]
RETURNS [Icons.IconFlavor];
Obtain an icon flavor for the icon associated with iconName. Create a new icon flavor if one has not previously been created.
If for some reason it could not obtain the icon, and default # unInit, returns the default. Otherwise, raises Error (defined below) with appropriate parameters.
InvalidateCache:
PROC [iconName: Rope.
ROPE ←
NIL];
If an iconFlavor was previous created for this icon, discard the flavor, i.e. the next call to GetIcon will create a new flavor. If iconName = NIL, invalidate the cache for all registered icons. Nop if iconName not registered.
WriteCatalogue:
PROC[ file: Rope.
ROPE ];
For all registered icons, appends their registration to the supplied file.
ReadCatalogue:
PROC[ file: Rope.
ROPE, errlog:
IO.
STREAM ←
NIL ];
Add all catalogued information to the current icon database.
Signals
Failed: ERROR [why: Failure, reason: Rope.ROPE];
Failure:
TYPE = {badSegment, noSuchIcon, fileNotFound, invalidIndex};
badSegment => segment name supplied to EstablishDB not legal or not $Icons segment
NoSuchIcon => corresponding name was not found in database
FileNotFound => the icon file could not be found,
InvalidIndex => index too large, i.e. not that many icons in the file.