get_icons()

Fetches the icons (GIF images) for one or more icon IDs via the cnv.GetIcons server job. These are the icons used in the archive area and hit lists, including custom icons.

The required icon IDs come from the object definition (the IconID attribute, exposed as icon_id on the object-type definition) or, per document, from document.system.file_properties.iconid.

1. Signature

  • Sync

  • Async

ecm.system.get_icons(*icon_ids: int) -> dict[int, bytes]
await ecm.system.get_icons(*icon_ids: int) -> dict[int, bytes]

2. Parameters

Name Type Description

*icon_ids

int

One or more numeric icon IDs. Passing none returns an empty dict without contacting the server.

3. Return value

A dict[int, bytes] mapping each resolved icon ID to its raw GIF bytes.

IDs the server does not know are silently omitted, so the result may be smaller than the request; an entirely unknown request yields an empty dict. There is no "all icons" mode: cnv.GetIcons is ID-based, so the IDs must be known.

4. Examples

4.1. Fetch a single icon

  • Sync

  • Async

icons = ecm.system.get_icons(1073744046)
gif = icons[1073744046]            # b'GIF89a...'
icons = await ecm.system.get_icons(1073744046)
gif = icons[1073744046]

4.2. Export all type icons from the object definition

  • Sync

  • Async

from pathlib import Path

definition = ecm.system.definition()
ids = [
    obj.icon_id
    for cabinet in definition.cabinets.values()
    for obj in cabinet.objects.values()
    if obj.icon_id
]
for icon_id, data in ecm.system.get_icons(*ids).items():
    Path(f"icon_{icon_id}.gif").write_bytes(data)
from pathlib import Path

definition = await ecm.system.definition()
ids = [
    obj.icon_id
    for cabinet in definition.cabinets.values()
    for obj in cabinet.objects.values()
    if obj.icon_id
]
for icon_id, data in (await ecm.system.get_icons(*ids)).items():
    Path(f"icon_{icon_id}.gif").write_bytes(data)

5. See also

  • definition() — object definition holding the object types' icon_id values

  • Model reference — document.system.file_properties.iconid per document