Programming Guide

Returns an integer handle for an application component

#include <smuprapi.h>

int sm_prop_id(char *obj_name);

obj_name

A string that identifies an object in the current application. The string must conform to Panther object name conventions. For information about valid formats, refer to "Properties" in Application Development Guide.

For example, this call to sm_prop_id gets a handle to the cust_id widget in the custlist screen:

err = sm_prop_id
      ("@screen('custlist')!@widget('cust_id')");

A non-subscripted widget identifier returns a handle to the entire widget. If the widget is an array, you can use this handle to get or set properties for all occurrences and elements. You can also create handle to an array that lets you get or set properties for individual occurrences or elements. To do this, include an empty subscript in the widget's string identifier, using one of these two formats:

• widget-spec[] enables access to properties of occurrences in widget-spec.

• widget-spec[[]] enables access to properties of elements in widget-spec.

  For example, the handle returned by this call to sm_prop_id can be used as an argument to variants of sm_prop_get_x_prop-type to get or set properties of elements in cust_id:

  sm_prop_id("@widget('cust_id')[[]]");

  Refer to Description for more information about obtaining access to the properties of an array's occurrences or elements.

• 1 Integer handle to the specified object.

• · PR_E_ERROR: Failed for another reason.

• · PR_E_OBJID: Object ID does not exist.

• · PR_E_OBJECT: Object does not exist.

• · PR_E_ITEM: Invalid element or occurrence.

sm_prop_id gets an integer handle to an application component—widgets and array elements or occurrences. Use this handle to get and change the component's properties with calls to functions like sm_prop_get_str or sm_prop_set_int.

You can get three kinds of handles to an array, depending on whether the array's string identifier contains a subscript and the subscript's format:

• A non-subscripted identifier returns a handle that lets you get or set properties for the array as a whole. The following sequence of calls changes the reverse property for all elements and occurrences in array cust_id:

  arr_h = sm_prop_id("cust_id");
  sm_prop_set_int(arr_h, PR_REVERSE, PV_YES);

• An empty subscript of single paired brackets—[]—returns a handle to an array that you can supply to _x variants of sm_prop_get and sm_prop_set to get and set properties of individual occurrences. The following sequence of calls changes the reverse property for the first occurrence in array cust_id:

  occ_h = sm_prop_id("cust_id[]");
  sm_prop_set_x_int(occ_h, 1, PR_REVERSE, PV_YES);

• An empty subscript of double paired brackets—[[]]—returns a handle to an array that you can supply to _x variants of sm_prop_get and sm_prop_set, to get and set properties of individual elements. The following sequence of calls changes the reverse property for the first element in array cust_id:

  elem_h = sm_prop_id("cust_id[[]]");
  sm_prop_set_x_int(elem_h, 1, PR_REVERSE, PV_YES);

sm_prop_get, sm_prop_set

---

---