| Programming Guide | |
Sorts the object's occurrences according to grid conventions
int sm_obj_sort_auto(int obj_id);
obj_id- An integer handle that identifies the object to be sorted. For widgets, it can be obtained from sm_prop_id.
- 0: Success. Target has been sorted without error.
PR_E_OBJECT: Cannot find target object.
PR_E_NO_SORT_FUNC: Sort order function not specified.
PR_E_SORT_FUNC: Sort order function not found, or error reported by sort order function.
PR_E_DATA_FORMAT: Incompatible data format for sort order.
sm_obj_sort_autosorts the object's occurrences according to the rules specified for grids in the Windows API. For fields that have their Column Click Action property set toPV_SORT, this function is invoked automatically in response to user clicks on the field's grid column heading.What happens in response to the invocation of
sm_obj_sort_autoon a given field depends on the settings of the field's runtime propertiescolumn_arrow_directionandcolumn_arrow_hidden.If
column_arrow_hiddenis set toPV_NO, the value ofcolumn_arrow_directionwill be flipped fromPV_UPtoPV_DOWN, or vice versa, and the object will be sorted according to the newcolumn_arrow_directionvalue.If
column_arrow_hiddenis set toPV_YES, then the field is sorted according to the current value ofcolumn_arrow_direction, and then the value ofcolumn_arrow_hiddenis changed toPV_NO.Note that these column arrow properties are in effect, and are manipulated by
sm_obj_sort_auto, even when an object is not in a grid and when there is no visible representation of the arrow on the screen.Access to
sm_obj_sort_autois provided if you want to invoke it in the context of customcolumn_click_funcfunctions.sm_obj_sort_autoshould either be called in response to column click events or during screen entry processing, so that the first time a user sees a grid, it is already sorted. In general,sm_obj_sort_autois not useful except for objects in grids. For general-purpose sorting of objects and synchronization groups, use sm_obj_sort.