| | 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.
sm_list_objects_nextreturns a handle to the next widget in the object contents list created bysm_list_objects_start. When this list is created, it contains the object IDs of all widgets within the container object. The first call tosm_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 usesm_list_objects_countto 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_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_endon the list to destroy it and deallocate its memory.
sm_list_objects_count, sm_list_objects_end, sm_list_objects_start