Programming Guide

Traverses the widgets contained by an application object

int sm_list_objects_next(int list_id);

list_id

An integer handle to the list of widgets in an application object, obtained from sm_list_objects_start.

• 1 The object ID of the next widget listed for the specified container object.

• · PR_E_ERROR: The list is empty.

• · PR_E_OBJID: Unable to find the specified list handle.

sm_list_objects_next returns a handle to the next widget in the object contents list created by sm_list_objects_start. When this list is created, it contains the object IDs of all widgets within the container object. The first call to sm_list_objects_next on a given list returns the object ID of the first widget on the list; each subsequent call returns the object ID of the next-listed widget; it also removes the last-returned object ID and thereby reduces the number of listed objects by one.

When the list is completely traversed, the function returns PR_E_ERROR. You can use this error code to test whether a list is fully traversed; or use sm_list_objects_count to set a counter for traversing the list.

For example, the following code creates an objects contents list for all members in a grid and traverses the list:

proc traverse_grid(grid_name)
vars grid_list, ct, member_ct, member_id

// create list of all members in grid
grid_list = sm_list_objects_start(sm_prop_id(grid_name))

if grid_list > 0
{
	// get count of listed object IDs
	member_ct = sm_list_objects_count(grid_list)

	for ct = 1 while ct <= member_ct
	// traverse list
	{
		member_id = sm_list_objects_next(grid_list)
		// use member's object ID to perform some action on it
	}
	call sm_list_objects_end(grid_list)
	return 1
}
return 0

sm_list_objects_next does not check whether the widgets identified in an object contents list are still in existence; it is therefore possible to return invalid object IDs for widgets that were destroyed after the list's creation.

When you are finished traversing an object contents list, call sm_list_objects_end on the list to destroy it and deallocate its memory.

sm_list_objects_count, sm_list_objects_end, sm_list_objects_start

---

---