gstream-set_input_error_handler(3)

1set_input_error_handler(3)      gstream manual      set_input_error_handler(3)
2
3
4

NAME

6       set_input_error_handler
7

SYNOPSIS

9       #include <gstream.h>
10
11
12       void set_input_error_handler(int error);
13

DESCRIPTION

15       Sets an error handler that will be called of the inputter encounter any
16       unusual, erratic behaviour, e.g. the user trying to move the cursor off
17       the  string  or pressing invalid keys. The handler is passed a constant
18       which currently can be one of the following:
19
20       IE_UNRECOGNIZED_KEY
21
22       The inputted key couldn't be used for anything, i.e. it wasn't  one  of
23       the  recognized  control  keys (for example KEY_LEFT, but not KEY_PGDN)
24       and the input approver didn't accept it as a valid char either.
25
26       IE_CURSOR_EXCEEDING_LIMITS
27
28       The user tried to move the cursor off the input  string,  e.g.  if  the
29       cursor  is at the beginning of the string and the user presses KEY_LEFT
30       or KEY_HOME. Note that pressing KEY_UP and KEY_DOWN  currently  returns
31       IE_CURSOR_EXCEEDING_LIMITS, no matter where the cursor is.
32
33       IE_NO_ROOM_FOR_CHAR
34
35       There  was  no  room  for  the  inputted char. This often occurs if the
36       length of the input string has been limited to a certain  maximum  with
37       set_max_input_length, but may also happen if the buffer that the input‐
38       ter puts the data in is full. The latter is not likely to happen unless
39       you,  for  instance,  force  the gstream to use your own buffer, as the
40       standard buffer is rather large.
41
42       Note that these constants are defined in 'gbuf' so you have to put
43
44          int stupid_mistakes = 0;
45
46          void ieh_for_my_number_inputter(int e)
47          {
48            switch (e) {
49              case gbuf::IE_UNRECOGNIZED_KEY:  // note: gbuf::
50                   if (stupid_mistakes > MUST_BE_BRAIN_DEAD) {
51                     say_to_user("Sorry, you can only input numbers!");
52                     user_characteristics = FOOL;
53                     stupid_mistakes = 0;
54                   }
55                   else
56                     ++stupid_mistakes;
57                   break;
58              case gbuf::IE_NO_ROOM_FOR_CHAR:
59                   play_quiet_beep();
60                   break;
61             } // in all other situations: do nothing
62          }
63
64       You should be aware that the inputter automatically will take  care  of
65       any  problems encountered and solve them with much elegance (often sim‐
66       ply by ignoring the user if the result of the action would be illegal),
67       so  your  error  handler doesn't really deal with the problem or handle
68       the situation - it is merely a way for you to warn  or  tell  the  user
69       that he is doing something wrong.
70
71       Some  advices concerning the style is given here - of course, you don't
72       have to follow them, you are free to  have  you  own  opinion  and  the
73       advices  are  general  so they might not fit your particular situation,
74       but please at least read them through before you begin  designing  your
75       own error handler:
76
77       Often  the  best thing to do is not to do anything. For example, simply
78       ignoring that the user is pressing an unrecognized key is often  better
79       than  complaining,  unless you have a specific reason for warning him -
80       in the example above the user should be aware that he was  supposed  to
81       enter a number
82
83       If  you  decide  to  do something, remember the KISS principle: keep it
84       simple. If you as a user have made a mistake, you're  probably  already
85       irritated  because  of that and then it doesn't help the situation that
86       you have to watch the screen go beserk (or  hear  an  entire  symphony)
87       before you can continue
88
89       If  you play a sound, such as a beep, make it a short, quiet one.  Per‐
90       sonally I can't stand a hysterical "BEEEEEEEEEP" if I accidentally  hit
91       the wrong key
92
93       Generally  don't  use large special effects. If you have invented a new
94       kind of plasma generator, you're probably better off releasing  a  demo
95       that  shows it, instead of making your users annoyed by forcing them to
96       look at it everytime they make the slightest fault
97
98       If you display a message, consider implementing a system  like  in  the
99       example above where the user is given a few tries before the message is
100       displayed, to ensure it is only (or mostly) sent  to  newbies.  If  the
101       example  should be perfect, it would even reset the mistake counter now
102       and then
103
104
105       At last a practical advice:  keep  in  mind  that  future  versions  of
106       gstream  may  have  more error codes added, so design the function in a
107       way that it won't break as soon as that happens (e.g.  don't  count  on
108       that  if you test for the first constants, then the remaining has to be
109       the last)
110
111       There is a typedef, 'input_error_handler', in 'gbuf' for the type of  a
112       pointer to a handler function:
113
114          gbuf::input_error_handler tmp_ieh;
115
116          //...
117
118          tmp_ieh = gs1.get_input_error_handler();
119          gs1.set_input_error_handler(gs2.get_input_error_handler());
120          gs2.set_input_error_handler(tmp_ieh);
121
122       The default input error handler is 'ieh_never_complain'.
123
124

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO