# Programming with Picture Ring Controls

Picture ring controls contain an indexed set of image/value pairs. Images are bitmaps that appear on the ring, and values can be of any type.

Use SetCtrlVal to set the active item of a picture ring control to the first of its items that matches a given value. Use SetCtrlIndex to set the active item based on a given zero-based index.

GetNumListItems obtains the number of items contained in a picture ring control. ClearListCtrl clears the contents of a picture ring control.

InsertListItem, ReplaceListItem and DeleteListItem operate on individual items.

GetValueFromIndex and GetIndexFromValue allow you to convert between values and indices.

Use GetCtrlVal to obtain the value of the currently selected picture ring item. Use GetCtrlIndex to obtain the zero-based index of the currently active item.

A picture ring control has a data type associated with it, so you must be careful to match the values you pass to some of the functions above with the data type of the control. The pointers you pass to functions which return values must also be compatible with the current data type of the control.

If the data type of the picture ring is VAL_STRING, then use GetValueLengthFromIndex to determine the size of the buffer needed to get the value strings. Keep in mind that the functions which return values append a NULL byte to the end of the text string, so you must make the buffer one byte larger than the value that you obtain from GetValueLengthFromIndex.

Use SetCtrlBitmap to change the image for an item in the picture ring control. Use GetCtrlBitmap to obtain a bitmap copy of the image for an item in the picture ring control.