| 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);
obj_id- 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.array_item- The widget occurrence or element whose property you want to get.
prop- The property to get. Refer to Chapter 1, "Runtime Properties," in Quick Reference for a full list of property constants.
prop_item- Specifies the item in a multi-item property whose value you want to get. For example, if the
propvalue isSM_PR_CONTROL_STRING, supply a logical key name such as XMIT to get that key's current control string assignment.
sm_prop_gethas three basic variants:sm_prop_get_str,sm_prop_get_intandsm_prop_get_dbl, which get string, integer, and double properties, respectively. For example,sm_prop_get_strgets string properties such astitle, whilesm_prop_get_intgets integer properties such asmax_occurrences.
sm_prop_get_strstores 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
_xand_mvariants. 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.
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 anobj_idhandle to the array and anarray_itemargument. Depending on how theobj_idhandle was obtained, the function determines whetherarray_itemspecifies an offset into the array's elements or its occurrences:
- To set the properties of an array's elements, obtain a handle by supplying sm_prop_id with a widget identifier that has the format
widget-spec[[]].
- To set the properties of an array's occurrences, obtain a handle by supplying sm_prop_id with a widget identifier that has the format
widget-spec[].
For example, this call to
sm_prop_idgets a handle to the properties ofcust_id's elements:int elem_h;
elem_h = sm_prop_id("cust_id[[]]");This call gets a handle to the properties of
cust_id'soccurrences:int occ_h;
occ_h = sm_prop_id("cust_id[]");Given these two handles, you can use
sm_prop_get_x_intto get themdtproperty setting for eithercust_id'sfirst 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);
sm_prop_get_m_prop-typegets one of the settings in a multi-item property such asPR_DROP_DOWN_DATAfor an option menu, orPR_CONTROL_STRINGfor a screen. For example, this code iteratively callssm_prop_get_m_strto compare the data in each item in option menuflavorsto 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,
PR_DROP_DOWN_DATA, ct)
if (!option_txt)
{
err = PR_E_ERROR;
break;
}
if (strcmp(option_txt, cur_item) == 0)
{
err = sm_prop_set_m_str(f_id,
PR_DROP_DOWN_DATA, ct, new_item);
break;
}
}
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 acceptNULLor 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_intand 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.
sm_prop_error, sm_prop_id, sm_prop_set