Using Value Map Annotation

To create a value map

1. Create a mapping string.

   A mapping string is a list of a control's numeric values corresponding to a human-readable string in Unicode. It starts with "A:" followed by a number that indicates the type of index used. Only image indexes are supported; therefore the index type is always 0.

   The string is followed by :index:result pairs. The "index" is a number representing an image index for a List-View or Tree-View, or the value for a slider control.

   The resulting value is a number obtained when you map the Role or State property for a list view or tree view control. Such numbers are expressed in decimal or hexadecimal with an "0x" prefix.

   The mapping string is always terminated with a final colon (":").

   The following is an example of an annotation map for the State and Role properties of a check box in a list view or tree view control. There are two items in the view that represent check boxes, and each has images corresponding to the checked and unchecked state.

   LPCWSTR g_ListOrTreeStateMap = 
   L"A:0"     // Index type; always 0. !
   L":0:0x00" // Image 0 is normal !
   L":1:0x10" // Image 1 is checked - STATE_SYSTEM_CHECKED (0x10) !
   L":";
   
   LPCWSTR g_ListOrTreeRoleMap = 
   L"A:0"     // Index type; always 0. !
   L":0:0x2C" // Image 0 is a check box - ROLE_SYSTEM_CHECKBUTTON
   (0x2c) !
   L":1:0x2C" // image 1 is also a check box !
   L":";
   

   For valid Role and State values, see Object Roles and Object State Constants.

   The index value may be negative when you map properties for a slider control.

   When you map a Value or Description property, the result is a string. Strings are not quoted and the colons act as delimiters.

   For more information, see Annotation Map Format.

2. Create the annotation manager and obtain a pointer to itsIAccPropServicesinterface.

   The following is an example of how to create the annotation manager.

   IAccPropServices * pAccPropSvc = NULL;
   HRESULT hr = CoCreateInstance(CLSID_AccPropServices, NULL,
   CLSCTX_SERVER, IID_IAccPropServices, (void**) & pAccPropSvc));
   
   

3. Attach the mapping string to the control.

   Call IAccPropServices::SetHwndPropStr, passing the HWND of the control and a pointer to the mapping string.

   The IdProp parameter will be one of the following.

   Parameter	Used for
   MSAAPROPID_ROLEMAP	To set a role map for list view or tree view controls.
   MSAAPROPID_STATEMAP	To set a state map for list view or tree view controls.
   PROPID_ACC_DESCRIPTIONMAP	To set a description map for list view or tree views.
   MSAAPROPID_VALUEMAP	To set a value map on slider controls.

    

4. Clean up.

   Before you destroy any value map annotated controls (for example, when handling WM_DESTROY), you must clear previously registered properties and release the annotation manager.

   To do this, call IAccPropServices::ClearHwndProps as appropriate and release your pointer to IAccPropServices.

For sample code, see Value Map Annotation Sample.