Programming the high-level User Interface

Handling keypad input

Under normal circumstances (no user entry errors), double_in() should work as shown in figure 1.14. The string prompt input is printed to the LCD with printf_lcd(), a user keys in a floating-point number and presses keyboard_return, fgets_keypad() gets the string from the keypad, and then the C library function sscanf() converts this to a double floating-point number, which is returned to the calling program.

1. The prototype of fgets_keypad() is

   char * fgets_keypad(char *buf, int buflen);

   The first argument is a pointer to a string (buffer) that holds the user-entered characters. The second argument is the maximum number of characters to be read (including the null character) into the buffer.

2. The prototype of sscanf()¹ is

   int sscanf(const char *s, const char *format, ...);

   The first argument s is a pointer to a string (e.g., "50.75"); the second argument is a conversion format specifier (e.g., "%lf" for a long float, a double); and the third argument should be a pointer to a double variable that will store the converted floating-point number (e.g., &val for a double val).

Handling input errors

When designing a user interface it is important to anticipate possible entry errors. When an invalid number is entered, double_in should operate as illustrated in figure 1.15.

In the case of entering a floating-point number on the keypad, there are four possible entry errors, as shown in table 1.11. The table also specifies an error message for each case. The double_in() function must detect each of these errors, print the corresponding error message on the LCD, and prompt the user again.

Our goal here is that the user must enter a valid number string before it can be converted to a double and returned to the calling program. Detecting error conditions is a matter of testing the string written by fgets_keypad().

Three functions from the C standard library header string.h² will be helpful for these tests. The strpbrk() function³ prototype is

char* strpbrk(const char *s1, const char *s2);

The function looks for the first occurrence of any character of string s1 in string s2 and, if found, returns a pointer to the string. If none is found, strpbrk() returns the null pointer, which is typically given the constant NULL. The and keys will be assigned ASCII characters [ and ]; therefore, if we look for "[]" in a string, strpbrk() returns NULL only if neither character appears in the string.

Using strpbrk() to detect the presence of bad characters (keys) works well. However, we must also detect multiple decimal points. One decimal point is valid, but two is too many. The strchr() and strrchr() functions⁴ are useful for detecting multiple decimal points. Their prototypes are

char* strchr(const char *s, int c);   // first occurrence of c in s
char* strrchr(const char *s, int c);  // last occurrence of c in s

These look for the first (strchr()) or last (strrchr()) occurrence of character⁵ c in string s and return a pointer to the character, if found. Otherwise, they return NULL. For example, the following program prints the substrings corresponding to the first and last occurrences of the character 't' in the string "attracting".

int main(void) {
  const char *s = "attracting";
  char *tf = strchr(s, 't');
  char *tl = strrchr(s, 't');
  printf("Truncated '%s':\nat first 't': %s\nat last 't': %s",
    s, tf, tl);
  return 0;
}

Its output is

Truncated 'attracting':
at first 't': ttracting
at last 't': ting

How might we use strchr() to determine if the user’s string contains a minus sign ('-') past the first character? How might we use strchr() and strrchr() to determine if the user’s string contains multiple decimal points? Hint: Consider what strchr() and strrchr() return when they both find the same decimal point. What if there is no decimal point? What if there are multiple decimal points?

Putting all these ideas together, let’s expand into a more detailed strategy for double_in():

1. Begin by using the printf_lcd() function to clear the LCD screen (see subsection L1.4 for the list of escape sequences that can be used).

2. Set a flag indicating that the keypad entry process has not been completed. For example, using an integer variable: err = 1;

3. Enter and stay in a while loop while err == 1;

   Within the loop (as described next), prompt the user and issue error messages until a string with no errors has been entered, and then set the flag err to 0.

4. After the loop, use sscanf() to perform the ASCII-string-to-double conversion, and return the result.
   Hint: Recall that because sscanf() is converting to a variable of type double, you must use the format %lf (long float).

Within the while loop:

• Use printf_lcd() to move the cursor to the start of line 1 and display the prompt. Then, check for the four specific errors as follows:

  1. Use fgets_keypad() “Get String” to obtain the string from the keypad.

     Note: If no digits are entered, fgets_keypads() returns a NULL, a string of zero length.

  2. Use the strpbrk() “String Pointer Break” to detect or in the string. Note: is returned by fgets_keypad() as the ASCII character '[', and as ']'.

  3. Use the strchr() to detect minus signs '-' the first character.

  4. Use the combination of strchr() and strrchr() to detect multiple decimal points.

• If any of the four errors occur, clear the display, move the cursor to line 2, and print the appropriate error message shown in Table 1.11. Alternatively, if the user-entered string passes all of the tests, set err=0.

Note: printf_lcd() and fgets_keypad() work like the standard C functions printf() and fgets(), and they are linked to your program from the T1 C library.

Parsing the variable argument list with vsnprintf()

The C function vsnprintf() writes formatted data from the variable argument list to a buffer (string) of a specified size.⁶ For instance, after invoking va_start() with argument pointer ap, char string[80], and int n,

va_list args;
   
va_start(args, format);
  n = vsnprintf(string, 80, format, args);
va_end(args);

This writes the arguments to a formatted string of length 80 chars according to format (i.e., the first argument of printf_lcd()). If successful, the returned value n is the number of characters written in the string. However, if an encoding error occurs, a negative error code n will be returned.

Printing each character with putchar_lcd()

Now that the arguments are parsed, we must write the resulting string to write to the LCD. The lower-level display driver function putchar_lcd() writes a single character to the LCD. Placed in a loop, putchar_lcd() can write successive characters of the string until the \0 null character that ends the string is encountered.

Although array subscripts and the standard C function strlen might be used to implement this loop, the use of pointers makes the task simple and efficient. Here is a useful idiom for looping through an entire string using a pointer p:

char *p = string;               // point to string start
while (*p) putchar_lcd(*p++);   // loop/put until char is \0

Notice that the \0 char evaluates to false (whereas all others are true), so this loop stops when the string is finished. The expression *p++, equivalent to (*p)++, evaluates to the dereferenced p first, then increments the pointer p (see section 2.4 for operator precedence and associativity rules).

The function putchar_lcd() places a single character corresponding to its argument on the LCD. Its prototype is

int putchar_lcd(int c);

For example, calls to putchar_lcd() might be

ch = putchar_lcd('m');          // put and assign 'm' to ch
putchar_lcd('\n');              // new line, ignore return value

All this culminates in the pseudocode shown in .