Name Property

[This is preliminary documentation and subject to change.]

The Name property, retrieved by calling the IAccessible::get_accName method, is a string used by accessibility aids to identify, find, or announce an object for the user. For example, the text on a button control is its name, while the name for a list box or edit control is the text from an associated static text control. Even graphics objects or owner-draw controls that don't display a name should maintain text to provide when queried for the Name property.

It is the server's task to make object names as intuitive as possible. Additionally, the server must make an object's Name property unique relative to any sibling objects in the parent container. This allows accessibility aids (clients) to narrow the object's meaning or purpose more easily.

Navigation within tables presents especially difficult problems for some users. Therefore, server applications should use table cell names that are as descriptive as possible. For example, a server could name a cell by combining the names of the rows and columns it occupies. These can be like "A1," but it is generally more descriptive to use row and column names when available, such as "Tom, February."

Servers, by way of the IAccessible::put_accName method, can allow the client to set an object's name. Servers can choose to assist users by allowing them to assign unique and persistent names for objects. This allows the user to tag objects with names that they use to easily return their focus to the object later. A server must provide its own storage for persistent names. If a server doesn't support the IAccessible::put_accName method, it fails the call by returning S_FALSE.

If an object does not have access to its Name property it should delegate requests to its parent, identifying itself by its child ID. For example, if a client asks an edit control for its name, the edit control will probably delegate the query to its parent, which would return the value of the static text control that labels the edit control. In other cases, the child object might be able to retrieve the text itself. However, the server must be careful to ensure that a parent and child do not each delegate calls to each other.