[AD] A proposed solution to the alert issue

[Marcio Fialho <maaf1980@xxxxxxxxxx>]

!!! Warning: This message is long (around 150 lines) !!!

>From the "Overloading Alert" thread:

> > Just to throw a comment into this mix: I use alert almost exclusivley for 
> > error messages, so I usually want to show the status of one or more 
> > variables... thus, it may be worth considering a printf() style 
> > string/argument list for a new alert.
> >    
>
> I think that's a given... I see little use for a function for reporting 
> information that takes a single string as argument but doesn't take 
> printf() style arguments, personally ;)
>
> Evert
>  
What about a function like this:

  allegro_textbox (int num_buttons, char *format,  [printf_style 
arguments], [buttons_arguments] );

with variable argument number?

This function would be a very generic textbox function, superseding 
alert and alert3 (which would probably be deprecated after 
allegro_textbox comes to light).   It could be used for very short 
messages or very long texts, with multiple buttons (like help menus, 
with scrolling bar), like in the examples below:

   allegro_textbox(0,"Hello world!\n Press ESC or ENTER to continue");

   allegro_textbox(3,  /* this textbox has three buttons */
       "\t\tDecision:\n\nYour score is %d. You have three "
       "choices now: button1, button2, button3",  /* format string */
       score,   /*multiple printf style arguments */
       "button1", '1',   /* button 1 string and keystroke */
       "button2", '2',   /* button 2 string and keystroke */
       "button3", '3');   /* button 1 string and keystroke */

Internally, this function would have a buffer 4096 or 8192 bytes long 
for converting the format string and printf style arguments. In the case 
the user requires more space, we could provide an extension of it 
allowing the user to use an external buffer, like in the example below:

  allegro_textbox_ex (int num_buttons, char *buf, int bufsize, char 
*format,  [printf_style arguments], [buttons_arguments] );

code example:
  ....
  char *buf;  //buffer used for conversion
  buf = malloc (bufsize);  //bufsize, computed elsewhere, is the 
expected size the buffer must have.
  if  (buf != NULL)
    {  
         allegro_textbox_ex (nbuttons, buf, bufsize, format, .... /* 
multiple arguments */,
            .... /*multiple buttons arguments */
           );
     }
     else
         allegro_textbox (1,"Text dialog failed!\n" "Not enough memory 
for intermediate buffer",
            "&OK", 'O');
   ....


If you don't like the name "allegro_textbox", the name of the function 
can be any one of these already  proposed (message_alert, alert_message, 
text_alert, textarea_alert, etc ...) or the alternate name I'm proposing 
now ( textbox ). What about a contest to choose the name of the function 
? :-;

There are many open issues related to this function. For example:
    Is it viable to put buttons arguments after the printf style arguments?
    What is the best order for the arguments?
    What would be better: To send the buttons arguments in a struct or 
in the
         variable argument list?
    Should there be a limit to the number of buttons? (if there's no 
limit, we
         would have to provide a scroll bar for the buttons as well if 
num_buttons is
          too high).
    What about addons to the function: (e.g special escape characters, 
to centralize
       text, change color, etc). If we decide to add more features to 
the function in
       the future, we should reserve some escape characters, so the 
function could be
       expanded without breaking backward compatibility. (Would this be 
acceptable
       in the 4.2 branch?). I fell it should recognise at least the \n 
and \t escape
       sequences.


Evert, when do you intend to feature freeze the library? Do you think 
this function can make it into the 4.2 branch?  I'll probably be able to 
submit it only next Sunday, if no one volunteers to write it.
   I would *really* like to have it into 4.2 branch (or a simplified 
version of it, at least). That's because 4.2 will probably be the last 
stable branch to support DJGPP and Windows 95, and people still using 
old computers wouldn't be able to benefit from this improvement if it 
comes to light only in the 4.3 branch. And last, but not least. It would 
make coding much easier for myself (perhaps I'm a bit selfish at this 
point, he he he...).
   But by the other side, I don't wan't to delay even more the release 
of 4.2 (I guess many people can't wait any further for 4.2), and I don't 
want that this feature makes Allegro incompatible with a nicely written 
addon for Allegro. It would be terrible to add this function to Allegro 
just to discover in the future that someone else had a much better 
solution to this problem in an add-on and has been forced to remove it 
to make the add-on compatible again. Perhaps we should consult them, or 
better (which I fell is the right thing). They should keep contact with us.
   What do you (everyone who reads this) thinks about it?
   Any decision you take will be fine to me.

   I'm open for suggestions, flames, etc. But probably I'll only be 
able to read them after Thursday (01/27).
 
   Unfortunately, I'll not be able to check my e-mails until probably 
Friday. That's why I decided to write a long e-mail with most of my ideas.

Regards,
Marcio.

----------------
Preliminary description of allegro_textbox arguments:
   num_buttons is the number of buttons the textbox will have. In case 
the user wants just to display some text and no buttons (e.g. when 
debugging the game), num_buttons is 0. In this case the behaviour of 
allegro_textbox would be the same of alert (or alert3) with no buttons 
(to close the window, press 'SPACE' or 'ENTER' or 'ESC')
e.g:
   allegro_textbox(0,"This is a test");
   allegro_textbox(0,"Variable int1 is %d and variable double_2 is 
%lf\n Press ESC or ENTER or SPACE to close this window", int1, double_2);

If num_buttons is any value other than 0, after the printf style 
arguments, would come the button strings and shortcuts.