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 are defined either by including them in the local file RegisteredIcons.Catalogue, or as a user profile entry under the key RegisteredIcons. Each entry is of the form form iconName: fileName index, where fileName can be a full path name. Icons can be registered from programs via the procedure RegisterIcon. The definitons contained in RegisteredIcons.Catalogue and the user's profile will automatically be updated when the corresponding files are edited, or following a rollback. Only those entries that have been changed will be affected, i.e. unchanged iconflavors will be retained.
Icons can also be registered from programs via the procedure RegisterIcon.
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, redefine:
BOOL ←
FALSE, saveInCatalogue:
BOOL ←
FALSE];
Registers the indicated icon. If redefine is TRUE, this registration will replace any previous registation, otherwise, it will only take effect if iconName is unregistered. (This is to allow programs to register icons when they are loaded, but to allow any registrations specified by the user in his profile or catalogue to take precedence.) 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. This feature is used by the iconeditor.
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.