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 IconRegistry.GetIcon each place that the corresponding icon flavor is desired without having to distinguish the first call from subsequent calls. This has the advantage that as soon as the definition for that icon is changed, or the icon itself is edited, the new representation will take effect.
Icons can be registered from programs via the procedure RegisterIcon. In addition, all icons defined in the local file DBIcons.Catalogue are also registered. (Ultimately this should be, and probably will be, implemented via the data base facility.) DBIcons.Catalogue is a vanilla text file in which each entry is of the form iconName: fileName index, where fileName can be a full path name. Comments are permitted anywhere in the file. DBIcons.Catalogue is parsed the first time GetIcon, RegisterIcon, or IsRegistered is called, and the corresponding registrations are performed. If DBIcons.Catalogue has been parsed, it will be reparsed whenever it is saved by Tioga, and also following a rollback. However, only those entries that have been changed will be affected, i.e. unchanged iconflavors will be retained.
Procedures
RegisterIcon:
PROC [iconName: Rope.
ROPE, fileName: Rope.
ROPE, index:
CARDINAL, saveInCatalogue:
BOOL ←
FALSE];
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:
PRIVATE
PROC;
For all registered icons whose registration does not appear in, or differs from that in, RegisteredIcons.Catalogue, appends their registration to RegisteredIcons.Catalogue.
Signals
Failed: ERROR [why: Failure, reason: Rope.ROPE];
Failure:
TYPE = {noCatalogue, noSuchIcon, fileNotFound, invalidIndex};
NoCatalogue => no DBIcons.Catalogue.
NoSuchIcon => corresponding name was not found in DBIcons.Catalogue
FileNotFound => the icon file could not be found,
InvalidIndex => index too large, i.e. not that many icons in the file.