Programming Guide


Traverses the widgets contained by an application object

int sm_list_objects_next(int list_id);

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



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.

See Also

sm_list_objects_count, sm_list_objects_end, sm_list_objects_start