Programming with Picture Ring Controls
This topic describes how to complete the following tasks programmatically.
- Associating the data type of the picture ring control with values
- Converting between value and indices of items
- Creating a picture ring control
- Customizing the arrow appearance
- Deleting and replacing items in the picture ring control
- Obtaining the number of items
- Obtaining the value and index of the currently selected item
- Setting the active item
- Setting the default item
- Specifying the placement and sizing of the image
Creating a Picture Ring Control
Use the NewCtrl function to create a picture ring control. The picture ring control is empty initially. To insert items, call InsertListItem.
int picRing;
picRing = NewCtrl (panelHandle, CTRL_PICTURE_RING_LS, "Picture Ring", 35, 35);
SetCtrlAttribute (panelHandle, picRing, ATTR_DATA_TYPE, VAL_STRING);
InsertListItem (panelHandle, picRing, -1, "c:\\temp\\file_new_header.ico", "New header");
InsertListItem (panelHandle, picRing, -1, "c:\\temp\\file_new_project.ico", "New project");
InsertListItem (panelHandle, picRing, -1, "c:\\temp\\file_new_source.ico", "New source");
InsertListItem (panelHandle, picRing, -1, "c:\\temp\\file_new_project.ico", "New project");
Deleting and Replacing Items in the Picture Ring Control
Call DeleteListItem to delete a specified number of items from the picture ring control.
int idxToDel;
int numToDel;
GetCtrlVal (panelHandle, PANEL_INDEXDEL, &idxToDel);
GetCtrlVal (panelHandle, PANEL_DELITEMS, &numToDel);
DeleteListItem (panelHandle, PANEL_PICTURERING, idxToDel, numToDel);
Call ClearListCtrl to delete all of the items in the picture ring control.
ClearListCtrl (panelHandle, PANEL_PICTURERING);
Call SetCtrlBitmap to change an image with another one you specify.
int bitmapID;
GetBitmapFromFile ("c:\\temp\\openfoldericon.ico", &bitmapID);
SetCtrlBitmap (panelHandle, picRing, 0, bitmapID);
Associating the Data Type of the Picture Ring Control with Values
The data type for a picture ring determines the type of data you can use for the value of picture ring items. You must match the values you pass to some of the functions with the data type of the control. The pointers you pass to functions that return values must also be compatible with the current data type of the control.
To set the data type, use the ATTR_DATA_TYPE attribute.
SetCtrlAttribute (panelHandle, picRing, ATTR_DATA_TYPE, VAL_STRING);
Because the data type of the values in the picture ring is a character array, you must make sure the values you pass to the picture ring and pointers to obtain values from the picture ring are also string values.
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.
Obtaining the Number of Items
If you need to know the number of items in the ring control, call GetNumListItems.
int count;
GetNumListItems (panelHandle, PANEL_PICTURERING, &count);
Obtaining the Value and Index of the Currently Selected Item
You can determine the value and index of the item currently displayed in the picture ring.
char *selValue = NULL;
int valLength, selIndex;
GetCtrlIndex (panelHandle, picRing, &selIndex);
GetValueLengthFromIndex (panelHandle, picRing, selIndex, &valLength);
selValue = malloc (sizeof(char) * (valLength + 1));
GetCtrlVal (panelHandle, picRing, selValue);
SetCtrlVal (panelHandle, PANEL_INDEX, selIndex);
SetCtrlVal (panelHandle, PANEL_VALUE, selValue);
Converting between Value and Indices of Items
int getIndex, int length, int index;
char *value;
GetCtrlIndex (panelHandle, picRing, &index);
GetValueLengthFromIndex (panelHandle, picRing, index, &length);
value = malloc (sizeof(char) * (length + 1));
GetValueFromIndex (panelHandle, picRing, index, value);
SetCtrlVal (panelHandle, PANEL_RINGVAL, value);
GetCtrlVal (panelHandle, picRing, value);
GetIndexFromValue (panelHandle, picRing, &getIndex, value);
SetCtrlVal (panelHandle, PANEL_RINGIDX, getIndex);
Setting the Active Item
Specify the item to show in the picture ring. You can specify the item by value or by index.
int val, index;
GetCtrlVal (panelHandle, PANEL_ACTIVEVAL, &val);
SetCtrlVal (panelHandle, PANEL_PICTURERING, val); // Based on value
GetCtrlVal (panelHandle, PANEL_ACTIVEIDX, &index);
SetCtrlIndex (panelHandle, PANEL_PICTURERING, index); // Based on index
Setting the Default Item
First set the default item and then call DefaultCtrl to update the user interface.
// By index
SetCtrlAttribute (panelHandle, picRing, ATTR_DFLT_INDEX, 2);
DefaultCtrl (panelHandle, picRing);
// By value
SetCtrlAttribute (panelHandle, picRing, ATTR_DFLT_VALUE, 1);
DefaultCtrl (panelHandle, picRing);
Customizing the Arrow Appearance
Call SetCtrlAttribute to specify how you want the arrow to look.
SetCtrlAttribute (panelHandle, PANEL_PICTURERING, ATTR_INCDEC_WIDTH, 35);
Specifying the Placement and Sizing of the Image
The ATTR_FIT_MODE attribute determines where the image appears in the picture ring.
InsertListItem (panelHandle, PANEL_PICTURERINGIMAGE, -1, "c:\\temp\\openfoldericon.ico", 1);
SetCtrlAttribute (panelHandle, PANEL_PICTURERINGIMAGE, ATTR_FIT_MODE, VAL_SIZE_TO_IMAGE);
InsertListItem (panelHandle, PANEL_PICTURERINGPIC, -1, "c:\\temp\\openfoldericon.ico", 1);
SetCtrlAttribute (panelHandle, PANEL_PICTURERINGPIC, ATTR_FIT_MODE, VAL_SIZE_TO_PICTURE);
InsertListItem (panelHandle, PANEL_PICTURERINGCORNER, -1, "c:\\temp\\openfoldericon.ico", 1);
SetCtrlAttribute (panelHandle, PANEL_PICTURERINGCORNER, ATTR_FIT_MODE, VAL_PICT_CORNER);
InsertListItem (panelHandle, PANEL_PICTURERINGCENTER, -1, "c:\\temp\\openfoldericon.ico", 1);
SetCtrlAttribute (panelHandle, PANEL_PICTURERINGCENTER, ATTR_FIT_MODE, VAL_PICT_CENTER);
InsertListItem (panelHandle, PANEL_PICTURERINGTILE, -1, "c:\\temp\\openfoldericon.ico", 1);
SetCtrlAttribute (panelHandle, PANEL_PICTURERINGTILE, ATTR_FIT_MODE, VAL_PICT_TILE);
