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 RegisteredIcons.Catalogue are also registered. (Ultimately this should be, and probably will be, implemented via the data base facility.) RegisteredIcons.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. The same iconName can have more than one registration, in which case the package will try registrations in the inverse order they appear in the file (later ones take precedence over eaerlier ones), until it is able to obtain the corresponding icon (this enables a client to specify that an icon may appear in several places, e.g. on a local disk file, or on a remote server). Comments are permitted anywhere in the file.
RegisteredIcons.Catalogue is parsed the first time GetIcon, RegisterIcon, or IsRegistered is called, and the corresponding registrations are performed. If RegisteredIcons.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.
The IconEditor has been modified so that it displays the registered name, if any, of the current icon. Icons can be registered by filling in the Name field and clicking the Register button. This will also cause the definition for that icon to be written to the catalogue. Whenever the IconEditor saves a file containing icon definitions, it invalidates the cache for all registered icons defined in that file. Thus, when you edit and save a registered icon using the IconEditor, the next call to IconRegistry.GetIcon will create a icon flavor corresponding to the newer version. (Currently there is no way to tell which icons have in fact been changed. This is a performance issue which could be addressed if necessary).
Procedures
RegisterIcon:
PROC [iconName: Rope.
ROPE, fileName: Rope.
ROPE, index:
CARDINAL, saveInCatalogue:
BOOL ←
FALSE];
Registers the indicated icon. The new registration will be used, when possible, before any earlier registrations, 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 unable to find the indicated icon, and there is more than one registration for iconName, try subsequent registrations.
If unable to 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 RegisteredIcons.Catalogue.
NoSuchIcon => corresponding name was not found in RegisteredIcons.Catalogue
FileNotFound => the icon file could not be found,
InvalidIndex => index too large, i.e. not that many icons in the file.