Role Property

The Role property describes an object's user interface element. All objects support the Role property.

In many cases, the object's role is obvious. For example, windows have the ROLE_SYSTEM_WINDOW role and push buttons have the ROLE_SYSTEM_PUSHBUTTON role.

The Role property is retrieved by calling IAccessible::get_accRole.

Identifying an Object's Role

Microsoft Active Accessibility provides role constants, defined in oleacc.h, that identify common object roles. It is recommended that server developers use these predefined role values. If a predefined role constant is returned, clients use the GetRoleText function to retrieve a localized string that describes the role.

For animation controls, such as the animation control displayed when copying files, use ROLE_SYSTEM_ANIMATION. Graphics that are occasionally animated are described as ROLE_SYSTEM_GRAPHIC with the State property set to STATE_SYSTEM_ANIMATED.

Note that some roles are not easy to describe. For example, a folder's large-icon view allows arbitrary arrangement of icons, so its role could be described as ROLE_SYSTEM_GROUPING. Or, a control that provides items in fixed rows and columns could have the ROLE_SYSTEM_TABLE role. Since a role is used to communicate the use model to an end user, it is important to use the appropriate role. For example, if your control acts like a button, then use ROLE_SYSTEM_PUSHBUTTON.