Traverses the widgets contained by an application objectint 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_nextreturns 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_nexton 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
sm_list_objects_nextdoes 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