Programmer's Guide:
Using Icons

An icon is a small image that represents a type of item. SAAPI allows programmers to access and manipulate the icons used in eRoom through Icon objects, which implement the IERUIcon interface. There are two types of icons: standard icons and custom icons. Standard icons are built into eRoom. Custom icons are imported into a facility by eRoom users.

Standard icons are further broken down by category; there are categories of icons for each type of principal item represented by an icon. Category values are taken from the enum ERUIconCategory.

The Type property of IERUIcon indicates whether an icon is custom or standard. The values of the Type property are taken from the ERUIconType enumeration.

The ID property uniquely identifies an icon within the scope of its type and category. A custom icon and a standard icon may have the same ID, as may two standard icons from different categories, but all custom icons have distinct IDs, as do all standard icons within a category. Standard icon IDs are taken from the enum ERUStandardIcons.

Dim FolderPage As IERUItem
Dim ListPage As IERUItem
Dim FolderIcon As IERUIcon
Dim ListIcon As IERUIcon

Set FolderPage = Room.GetItemByPath("/Folder")
Set ListPage = Room.GetItemByPath("/List")
Set FolderIcon = FolderPage.PrincipalItem.Icon
Set ListIcon = ListPage.PrincipalItem.Icon
' Both FolderIcon and ListIcon could have a Type property of erIconTypeStandard
' and an ID of 0. But the two icons are different because they are in different
' categories. FolderIcon is the icon with an ID of 0 among the icons for folder
' items. ListIcon is the icon with ID of 0 among the icons for list items.
' If both FolderIcon and ListIcon have a Type property of erIconTypeCustom
' and ID property of 0, it means that the two icons are the same, because custom
' icon IDs are unique among the custom icons. In effect, all custom icons are
' in the same category, although there is no specific category defined for custom
' icons.

Adding custom icons to the facility

You can add your own icons to your eRoom facility by calling the AddIcon2 method of IERUFacility, supplying a .gif file as input:

Dim Facility As IERUFacility
Dim Icon As IERUIcon
Dim ID As Integer
Dim Type As ERUIconType

Set Facility = Manager.GetFacility("MyFacility", "")
Set Icon = Facility.AddIcon2("C:\\winnt\\web\LargeIcon.gif", "C:\\winnt\SmallIcon.gif")
' The return icon type would be erIconTypeCustom
Type = Icon.Type
ID = Icon.ID

Removing custom icons from the facility

You can remove custom icons from a facility, but you cannot remove standard icons. The following example removes the custom icon whose ID is 0:

Dim Facility As IERUFacility

Set Facility = Manager.GetFacility("MyFacility", "")
Facility.RemoveIcon 0

Note: If you delete a custom icon that is specified as the default icon for an object type or is assigned to a specific object in the room, the eRoom user interface automatically resets the default icon for the object type or specific object to the initial default icon.

Changing the default icon for an object type

When you change the default icon for an object type, you can select from a set of icons that includes all of the standard icons for that object-type category, plus all the custom icons in the facility. The IDs of the standard icons are listed in the ERUStandardIcons enum. After assigning a new default icon for an object type, all objects of that type which are defined to use the default icon will start using the new icon you specified.

The following example changes the default icon for Folder Pages:

Dim Facility As IERUFacility
Set Facility = Manager.GetFacility("MyFacility", "")
' Set the default icon to be one of the standard icons
Facility.SetDefaultIcon erIconCategoryFolderPage, erIconTypeStandard, _
erIconFolderCalendar
' Or set the default icon to be one of the custom icons
Facility.SetDefaultIcon erIconCategoryFolderPage, erIconTypeCustom, 0

Changing the icon for a specfic object

You also can change the icon for a specific object.

The following example changes the icon for one particular Folder Page:

Dim FolderPage As IERUItem

Set FolderPage = Room.GetItemByPath("/Folder")
FolderPage.PrincipalItem.SetIcon erIconTypeCustom, 0