Programming Guide


Gets a property setting

#include <smuprapi.h>
int sm_prop_get_int(int obj_id, int prop);
char *sm_prop_get_str(int obj_id, int prop);
double sm_prop_get_dbl(int obj_id, int prop);
int sm_prop_get_x_int(int obj_id, int array_item, int prop);
char *sm_prop_get_x_str(int obj_id, int array_item, int prop);
double sm_prop_get_x_dbl(int obj_id, int array_item, int prop);
int sm_prop_get_m_int(int obj_id, int prop, int prop_item);
char *sm_prop_get_m_str(int obj_id, int prop, int prop_item);
double sm_prop_get_m_dbl(int obj_id, int prop, int prop_item);

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

The widget occurrence or element whose property you want to get.

The property to get. 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 get. For example, if the prop value is SM_PR_CONTROL_STRING, supply a logical key name such as XMIT to get that key's current control string assignment.



sm_prop_get has three basic variants: sm_prop_get_str, sm_prop_get_int and sm_prop_get_dbl, which get string, integer, and double properties, respectively. For example, sm_prop_get_str gets string properties such as title, while sm_prop_get_int gets integer properties such as max_occurrences.

sm_prop_get_str stores the returned data in a pool of buffers that it shares with other functions; either process the returned string immediately or copy it to another variable for additional processing.

Each of these variants have _x and _m variants. These let you access 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 get properties for individual elements and occurrences in an array by calling sm_prop_get_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[[]]");

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 get the mdt property setting for either cust_id's first element or first occurrence as follows:

/* get the first element's mdt setting */
int elem_mdt;
elem_mdt = sm_prop_get_x_int(elem_h, 1, PR_MDT);
/* get the first occurrence's mdt setting */
int occ_mdt;
occ_mdt = sm_prop_get_x int(occ_h, 1, PR_MDT);
Multi-item Properties

sm_prop_get_m_prop-type gets one of the settings 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 iteratively calls sm_prop_get_m_str to compare the data in each item in option menu flavors to the current selection:

/* replace current item with contents of "substitute" */
char cur_item[256], new_item[256];
char *option_txt;
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);

A return value of 0 from sm_prop_get_str, sm_prop_get_dbl, or one of its variants usually indicates that the call failed. However, some string and double properties accept NULL or 0 values. To determine with absolute certainty whether a call failed and to get its error code, call sm_prop_error.

A negative value returned by sm_prop_get_int and its variants usually specifies an error. However, some integer properties accept negative values; in these cases, you can differentiate between a negative property value and an error condition only by calling sm_prop_error.

See Also

sm_prop_error, sm_prop_id, sm_prop_set