Using Value Map Annotation

  • Article

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 checkbox 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.

    2. 



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 checkbox - ROLE_SYSTEM_CHECKBUTTON (0x2c)
L":1:0x2C" // image 1 is also a checkbox
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](ms696112\(v=vs.85\).md).



    

  1. Create the annotation manager and obtain a pointer to its IAccPropServices interface.
    

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

    2. 



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



    

  1. 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.

    
    

    

    2. 

  2. 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.
    

    3. 



For sample code, see Value Map Annotation Sample.