Programming Guide


Sets a property

#include <smuprapi.h>
int sm_prop_set_int(int obj_id, int prop, int val);
int sm_prop_set_str(int obj_id, int prop, char *val);
int sm_prop_set_dbl(int obj_id, int prop, double val);
int sm_prop_set_x_int(int obj_id, int array_item, int prop, int val);
int sm_prop_set_x_str(int obj_id, int array_item, int prop, char *val);
int sm_prop_set_x_dbl(int obj_id, int array_item, int prop, double val);
int sm_prop_set_m_int(int obj_id, int prop, int prop_item, int val);
int sm_prop_set_m_str(int obj_id, int prop, int prop_item, char *val);
int sm_prop_set_m_dbl(int obj_id, int prop, int prop_item, double val);

An integer handle that identifies the Panther object whose property you want to set, obtained through sm_prop_id. For application properties, supply PR_APPLICATION; for the current screen, PR_CURSCREEN.

The widget occurrence or element whose value you want to set.

The property to set. Refer to Chapter 1, "Runtime Properties," in Quick Reference for a full list of property constants.

Specifies the item in a multi-item property whose value you want to set. For example, if prop is set to PR_CONTROL_STRING, supply a logical key name to get that key's current control string assignment.

The value to set for the specified property or property item. The value's type—string, integer, or double—must be appropriate to the property itself. For a list of properties and their valid values, refer to Chapter 1, "Runtime Properties," in Quick Reference.



sm_prop_set has three basic variants: sm_prop_set_str, sm_prop_set_int, and sm_prop_set_dbl, which set string, integer, and double properties, respectively. For example, sm_prop_set_str sets string properties such as title, while sm_prop_set_int sets integer properties such as max_occurrences.

Each of these variants have _x and _m variants. These let you set properties of occurrences or elements, and offsets into properties that take multiple values, respectively. These variant types are discussed in the following sections.

Elements and Occurrences

You can set properties for individual elements and occurrences in an array by calling sm_prop_set_x_prop-type. All variants of this function require an obj_id handle to the array and an array_item argument. Depending on how the obj_id handle was obtained, the function determines whether array_item specifies an offset into the array's elements or its occurrences:

For example, this call to sm_prop_id gets a handle to the properties of cust_id's elements:

int elem_h;
elem_h = sm_prop_id("cust_id[[]]");

Alternatively, this call gets a handle to the properties of cust_id's occurrences:

int occ_h;
occ_h = sm_prop_id("cust_id[]");

Given these two handles, you can use sm_prop_get_x_int to set the foreground color of either cust_id's first element or first occurrence as follows:

/*set the first element's foreground color */
sm_prop_set_x int(elem_h, 1, PR_FG_COLOR_NUM, MAGENTA);
/*set the first occurrence's foreground color */
sm_prop_set_x_int(occ_h, 1,PR_FG_COLOR_NUM, MAGENTA);

Note: To set properties on the entire array, use a handle obtained by supplying sm_prop_id with a widget string identifier that contains no subscript.

Multi-item Properties

sm_prop_set_m_prop-type sets one of the values in a multi-item property such as PR_DROP_DOWN_DATA for an option menu, or PR_CONTROL_STRING for a screen. For example, this code calls sm_prop_set_m_str to set the data for an item in option menu flavors:

/* replace current item with contents of "substitute" */
char cur_item[256], new_item[256];
char *option_txt[256];
int ct, f_id, err;

f_id = sm_prop_id("flavors");

/*get substitute data*/
sm_n_getfield("substitute", new_item);

/*get selection data*/
sm_n_getfield("flavors", cur_item);

/* get offset of current selection */
for (ct = 1; ; ct++)
option_txt = sm_prop_get_m_str(f_id,
if (!option_txt)
err = PR_E_ERROR;
if (strcmp(option_txt, cur_item) == 0)
err = sm_prop_set_m_str(f_id,
PR_DROP_DOWN_DATA, ct, new_item);

See Also

sm_prop_error, sm_prop_id, sm_prop_set