set_input_error_handler(3)

💖 set_input_error_handler 💖

okay bestie, so this one lives in the gstream manual, section 3 (library calls, obviously), and it's all about what happens when your inputter catches someone being a menace. sit down, grab a strawberry 🍓, let's go.

---

✨ NAME ✨

set_input_error_handler — the little function that decides who gets yelled at when the user does something goofy 💅

---

✨ SYNOPSIS ✨

#include <gstream.h>

void set_input_error_handler(int error);

---

✨ DESCRIPTION ✨

okay so here's the vibe: this sets an error handler that gets called whenever the inputter encounters any unusual, erratic behaviour. like, the user trying to move the cursor off the string, or pressing invalid keys. that kind of chaos. 🙈

and the handler gets passed a constant, which currently can be one of these:

• IE_UNRECOGNIZED_KEY — the key that got inputted couldn't be used for anything. like, it wasn't one of the recognized control keys (think KEY_LEFT, but not KEY_PGDN) and the input approver didn't accept it as a valid char either. so it's just... nothing. a void key. 💀
• IE_CURSOR_EXCEEDING_LIMITS — the user tried to move the cursor off the input string. e.g. cursor is at the beginning of the string and they press KEY_LEFT or KEY_HOME. also, heads up: pressing KEY_UP and KEY_DOWN currently returns IE_CURSOR_EXCEEDING_LIMITS no matter where the cursor is. yes, no matter where. that's just how it is, periodt.
• IE_NO_ROOM_FOR_CHAR — there was no room for the inputted char. this one shows up a lot when the length of the input string has been limited to a certain maximum with set_max_input_length, but it can also happen if the buffer that the inputter puts the data in is full. lowkey that second one is not likely to happen unless you, for instance, force the gstream to use your own buffer, because the standard buffer is rather large. it's chunky. it's fine. 🫶

note that these constants are defined in 'gbuf', so you have to put gbuf:: in front of them. no skipping, bestie.

and here's what that looks like in real life:

int stupid_mistakes = 0;

void ieh_for_my_number_inputter(int e)
{
  switch (e) {
    case gbuf::IE_UNRECOGNIZED_KEY:  // note: gbuf::
         if (stupid_mistakes > MUST_BE_BRAIN_DEAD) {
           say_to_user("Sorry, you can only input numbers!");
           user_characteristics = FOOL;
           stupid_mistakes = 0;
         }
         else
           ++stupid_mistakes;
         break;
    case gbuf::IE_NO_ROOM_FOR_CHAR:
         play_quiet_beep();
         break;
   } // in all other situations: do nothing
}

now, super important thing to understand: the inputter automatically takes care of any problems encountered and solves them with much elegance. often simply by ignoring the user if the result of the action would be illegal. so your error handler doesn't really deal with the problem or handle the situation — it is merely a way for you to warn or tell the user that he is doing something wrong. you're not the fixer, you're the notifier. main character energy in a supporting role, iykyk. 👑

---

🌸 some advice about style 🌸

this part is advice, and no cap, you don't have to follow it. you are free to have your own opinion, and these are general, so they might not fit your particular situation. but please at least read them through before you begin designing your own error handler. like, at least skim. for me. 🥺

• often the best thing to do is not to do anything. for example, simply ignoring that the user is pressing an unrecognized key is often better than complaining, unless you have a specific reason for warning him — in the example above, the user should be aware that he was supposed to enter a number.
• if you decide to do something, remember the KISS principle: keep it simple. if you as a user have made a mistake, you're probably already irritated because of that, and then it doesn't help the situation that you have to watch the screen go beserk (or hear an entire symphony) before you can continue. 😭
• if you play a sound, such as a beep, make it a short, quiet one. personally I can't stand a hysterical "BEEEEEEEEEP" if I accidentally hit the wrong key.
• generally don't use large special effects. if you have invented a new kind of plasma generator, you're probably better off releasing a demo that shows it, instead of making your users annoyed by forcing them to look at it everytime they make the slightest fault. let the plasma generator be its own moment. ✨
• if you display a message, consider implementing a system like in the example above where the user is given a few tries before the message is displayed, to ensure it is only (or mostly) sent to newbies. if the example should be perfect, it would even reset the mistake counter now and then. we love a forgiving queen. 🎀
• at last, a practical advice: keep in mind that future versions of gstream may have more error codes added, so design the function in a way that it won't break as soon as that happens (e.g. don't count on that if you test for the first constants, then the remaining has to be the last). future-proofing is self-care. 💜

---

🦋 the typedef 🦋

there is a typedef, 'input_error_handler', in 'gbuf' for the type of a pointer to a handler function:

gbuf::input_error_handler tmp_ieh;

//...

tmp_ieh = gs1.get_input_error_handler();
gs1.set_input_error_handler(gs2.get_input_error_handler());
gs2.set_input_error_handler(tmp_ieh);

look at that little swap dance. iconic. 💅

the default input error handler is 'ieh_never_complain'.

---

✨ SEE ALSO ✨

• gstream-get_input_error_handler(3)
• gstream-set_input_approver(3)
• gstream-set_max_input_length(3)
• gstream-ieh_never_complain(3)

---

and that's the whole page, bestie 🫶 this was the gstream manual, version 1.6, dated set_input_error_handler(3) — go forth and handle your errors with grace and a quiet beep. slay. 💖🌈⭐