Setting and fetching the field user pointer

As it does with panels and menus, ETI provides functions to manipulate an arbitrary pointer convenient for field data such as title strings, help messages, and the like.

SYNOPSIS

   int set_field_userptr (field, userptr)
   FIELD  field;
   char  userptr;
   

   char  field_userptr (field)
   FIELD  field;

``Using the field user pointer to match items'', for example, shows three routines that use these field functions:

set_field_id

allocates space for a struct ID to be associated with a field and calls set_field_userptr to establish the field's pointer to it

free_field_id

frees the space for the associated ID

find_field

searches the names associated with all fields on the form to determine whether any of them match an arbitrary name passed to it

   #define match(a,b)	(strcmp (a, b) == 0)
   

   typedef struct
   {
   	int		type;
   	char *		name;
   }
   	ID; /* to be hooked onto field userptr */
   

   void set_field_id (f, type, name) /* associate type and name with field f */
   FIELD * f;
   int type;
   char * name;
   {
   	ID * id = (ID *) malloc (sizeof (ID)); /* allocate space, see malloc(3C) */
   

   	if (id)                /* if space allocated */
   	{
   		id -> type = type;    /* assign type and name */
   		id -> name = name;
   	}
   	set_field_userptr (f, (char *) id);  /* point to id */
   }
   

   void free_field_id (f) /* free id connected to field */
   FIELD * f;
   {
   	x = (ID *) field_userptr (*f); /* fetch field user pointer */
   

   	if (x)
   		free (x);
   }
   

   FIELD * find_field (f, name) /* find field on form with name */
   FORM * form;
   char * name;
   {
   	FIELD ** f = form_fields (form);   /* fetch pointer to form's field array */
   	ID * x;
   

   	while (*f)                    / * for each field in the form */
   	{
   		x = (ID *) field_userptr (*f); /* fetch ID associated with field */
   

   		if (x && x -> name && match (name, x -> name))
   					 /* does its name match ? */
   			break;
   		++f;
   	}
   	return *f;  /* return field pointer of match or NULL */
   }

Using the field user pointer to match items

Note that if a match is not found, find_field returns a NULL field pointer. See the previous sections on panel and menu user pointers for more examples.

If successful, set_field_userptr returns E_OK. If not, it returns the following:

E_SYSTEM_ERROR -

system error