Programming Guide


Constructs a list of widgets contained by an application object

int sm_list_objects_start(int obj_id);

An integer handle that identifies the container object whose contents are to be listed, obtained through sm_prop_id or through the JPL id property.



sm_list_objects_start creates a list of all widgets that are currently contained by the specified object; the list identifies widgets by their object IDs. The function returns a handle to the list so you access its contents. The container object can be a screen (including one used as an LDB), grid widget, box widget, selection group, synchronized scrolling group, or table view widget.

All widgets within the container object are included in the list, even if they are themselves contained by other widgets. Two exceptions apply: the list that is generated for a box and or grid widget excludes any selection groups and synchronized scrolling groups that are inside the container object.

Widgets that accept data are listed in order of their position within the container object—from left to right, top to bottom. You can traverse an object contents list and thereby access the widgets in it by calling sm_list_objects_next; you can also count the listed objects with sm_list_objects_count. For an example, refer to sm_list_objects_next.

An ID to an object contents list is always returned, even when the list is empty. When you are done examining the list, be sure to free the memory allocated for it by calling sm_list_objects_end.

See Also

sm_list_objects_count, sm_list_objects_end, sm_list_objects_next, sm_prop_id