Programming with Ring Controls
This topic describes how to complete the following tasks programmatically.
- Associating the data type of the ring control with values
- Converting between label, value, and indices of items
- Creating a ring control
- Customizing the arrow appearance
- Deleting and replacing items in the ring control
- Obtaining the number of items
- Obtaining the value and index of the currently selected item
- Removing check marks from the ring control
- Setting the active item
- Setting the default item
- Setting text styles for ring items
Creating a Ring Control
Use the NewCtrl function to create a ring control. The ring control is empty initially. To insert items, call InsertListItem.
int ringCtrl;
ringCtrl = NewCtrl (panelHandle, CTRL_RING_LS, "Ring Control", 30, 30);
InsertListItem (panelHandle, ringCtrl, 0, "Ring Item 1", 1);
InsertListItem (panelHandle, ringCtrl, -1, "Ring Item 2", 2);
InsertListItem (panelHandle, ringCtrl, -1, "Ring Item 3", 3);
InsertListItem (panelHandle, ringCtrl, -1, "Ring Item 4", 4);
Setting the Active Item
You can set the active item based on ring item index or the value of the ring item.
int val, index;
GetCtrlVal (panelHandle, PANEL_NUMERIC, &val);
SetCtrlVal (panelHandle, ringCtrl, val); // Based on value
GetCtrlVal (panelHandle, PANEL_NUMERIC_2, &index);
SetCtrlIndex (panelHandle, ringCtrl, index); // Based on index
Deleting and Replacing Items in the Ring Control
Call DeleteListItem to delete a specified number of items from the ring control.
int idxToDel, numToDel;
GetCtrlVal (panelHandle, PANEL_NUMERIC_3, &idxToDel);
GetCtrlVal (panelHandle, PANEL_NUMERIC_4, &numToDel);
DeleteListItem (panelHandle, PANEL_RING, idxToDel, numToDel);
Call ClearListCtrl to delete all of the items in the ring control.
ClearListCtrl (panelHandle, ringCtrl);
Call ReplaceListItem to substitute one list item with another one you specify.
ReplaceListItem (panelHandle, ringCtrl, 2, "New Ring Item", 2);
Obtaining the Number of Items
int count;
GetNumListItems (panelHandle, PANEL_RING, &count);
Obtaining the Value and Index of the Currently Selected Item
int itemIndex, itemValue;
GetCtrlIndex (panelHandle, PANEL_RING, &itemIndex);
SetCtrlVal (panelHandle, PANEL_DEVINDEX, itemIndex);
GetCtrlVal (panelHandle, PANEL_RING, &itemValue);
SetCtrlVal (panelHandle, PANEL_VALINDEX, itemValue);
Associating the Data Type of the Ring Control with Values
The data type for a ring control determines the type of data you can use for the value of 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, dataRing, ATTR_DATA_TYPE, VAL_STRING);
Because the data type of the values in the ring control is a character array in this instance, you must make sure the values you pass to the ring control and pointers to obtain values from the ring control are also string values.
InsertListItem (panelHandle, dataRing, 0, "Int", "4 byte integer");
InsertListItem (panelHandle, dataRing, -1, "Char", "Single byte character");
InsertListItem (panelHandle, dataRing, -1, "Double", "8 byte floating point value");
InsertListItem (panelHandle, dataRing, -1, "String", "Character array");
Converting between Label, Value, and Indices of Items
You can convert between labels, values, and indices of ring control items.
/* Convert index to value. In this example, the data type of the ring control is VAL_STRING. */
int ringIdx, index, ringValLen, ringLabelLen;
char *ringValue = NULL, *ringLabel = NULL;
GetCtrlIndex (panelHandle, PANEL_RING, &ringIdx);
Because the data type of the ring is VAL_STRING, call GetValueLengthFromIndex to determine the size of the buffer needed to get the value strings. GetValueFromIndex appends a NULL byte to the end of the text string, so you must make the buffer 1 byte larger than the value obtained from GetValueLengthFromIndex.
GetValueLengthFromIndex (panelHandle, PANEL_RING, ringIdx, &ringValLen);
ringValue = malloc (sizeof(char) * (ringValLen + 1));
GetValueFromIndex (panelHandle, PANEL_RING, ringIdx, ringValue);
SetCtrlVal (panelHandle, PANEL_VALUE, ringValue);
// Convert index to label
GetLabelLengthFromIndex (panelHandle, PANEL_RING, ringIdx, &ringLabelLen);
GetLabelFromIndex appends a NULL byte to the end of the text string, so you must make the buffer 1 byte larger than the value obtained from GetLabelLengthFromIndex.
ringLabel = malloc (sizeof(char) * (ringLabelLen + 1));
GetLabelFromIndex (panelHandle, PANEL_RING, ringIdx, ringLabel);
SetCtrlVal (panelHandle, PANEL_LABEL, ringLabel);
// Convert value to index
GetIndexFromValue (panelHandle, PANEL_RING, &index, ringValue);
SetCtrlVal (panelHandle, PANEL_RINGINDEX, index);
Setting the Default Item
Specify the default item by index or by value. If you call the following example code after the call to LoadPanel, you must call DefaultCtrl to update the user interface.
// By index
SetCtrlAttribute (panelHandle, PANEL_RING, ATTR_DFLT_INDEX, 2);
DefaultCtrl (panelHandle, PANEL_RING);
// By value
SetCtrlAttribute (panelHandle, PANEL_RINGSLIDE, ATTR_DFLT_VALUE, 1);
DefaultCtrl (panelHandle, PANEL_RINGSLIDE);
Customizing the Arrow Appearance
SetCtrlAttribute (panelHandle, PANEL_RING_2, ATTR_INCDEC_WIDTH, 25);
SetCtrlAttribute (panelHandle, PANEL_RING, ATTR_MENU_ARROW_COLOR, VAL_RED);
SetCtrlAttribute (panelHandle, PANEL_RING, ATTR_MENU_ARROW_HEIGHT, 20);
SetCtrlAttribute (panelHandle, PANEL_RING, ATTR_MENU_ARROW_WIDTH, 20);
Removing Check Marks from the Ring Control
SetCtrlAttribute (panelHandle, PANEL_RING, ATTR_DISABLE_CHECK_MARK, 1);
Setting Text Styles for Ring Items
SetCtrlAttribute (panelHandle, ringCtrl, ATTR_TEXT_BOLD, 1);
SetCtrlAttribute (panelHandle, ringCtrl, ATTR_TEXT_FONT, "Times New Roman");
