src/bfu/msgbox.h

   1 #ifndef EL__BFU_MSGBOX_H
   2 #define EL__BFU_MSGBOX_H
   3
   4 #include "util/align.h"
   5 #include "util/memlist.h"
   6
   7 struct terminal;
   8
   9
  10 /* Bitmask specifying some @msg_box() function parameters attributes or
  11  * altering function operation. See @msg_box() description for details about
  12  * the flags effect. */
  13 enum msgbox_flags {
  14         /* {msg_box(.text)} is dynamically allocated */
  15         MSGBOX_FREE_TEXT = 0x1,
  16         /* The msg_box() string parameters should NOT be run through gettext
  17          * and translated. */
  18         MSGBOX_NO_INTL = 0x2,
  19         /* Should the text be scrollable */
  20         /* XXX: The text need to be allocated since it will be mangled */
  21         MSGBOX_SCROLLABLE = 0x4,
  22         /* i18nalize title and buttons but not the text. */
  23         MSGBOX_NO_TEXT_INTL = 0x8,
  24 };
  25
  26 /* This is _the_ dialog function used in almost all parts of the code. It is
  27  * used to easily format dialogs containing only text and few buttons below.
  28  *
  29  * @term        The terminal where the message box should appear.
  30  *
  31  * @mem_list    A list of pointers to allocated memory that should be
  32  *              free()'d when then dialog is closed. The list can be
  33  *              initialized using getml(args, NULL) using NULL as the end.
  34  *              This is useful especially when you pass stuff to @udata
  35  *              which you want to be free()d when not needed anymore.
  36  *
  37  * @flags       If the MSGBOX_FREE_TEXT flag is passed, @text is free()d upon
  38  *              the dialog's death. This is equivalent to adding @text to the
  39  *              @mem_list. Also, when this parameter is passed, @text is not
  40  *              automagically localized and it is up to the user to do it.
  41  *
  42  *              If the MSGBOX_NO_INTL flag is passed, @title, @text and button
  43  *              labels will not be localized automatically inside of msg_box()
  44  *              and it is up to the user to do the best job possible.
  45  *
  46  * @title       The title of the message box. It is automatically localized
  47  *              inside (unless MSGBOX_NO_INTL is passed).
  48  *
  49  * @align       Provides info about how @text should be aligned.
  50  *
  51  * @text        The info text of the message box. If the text requires
  52  *              formatting use msg_text(format, args...). This will allocate
  53  *              a string so remember to @align |= MSGBOX_FREE_TEXT.
  54  *
  55  *              If no formatting is needed just pass the string and don't
  56  *              @align |= MSGBOX_FREE_TEXT or you will get in trouble. ;)
  57  *
  58  *              The @text is automatically localized inside of msg_box(),
  59  *              unless MSGBOX_NO_INTL or MSGBOX_FREE_TEXT is passed. That is
  60  *              because you do NOT want to localize output of msg_text(),
  61  *              but rather individually the format string and parameters to
  62  *              its string conversions.
  63  *
  64  * @udata       Is a reference to any data that should be passed to
  65  *              the handlers associated with each button. NULL if none.
  66  *
  67  * @buttons     Denotes the number of buttons given as varadic arguments.
  68  *              For each button 3 arguments are extracted:
  69  *                      o First the label text. It is automatically localized
  70  *                        unless MSGBOX_NO_INTL is passed. If NULL, this button
  71  *                        is skipped.
  72  *                      o Second pointer to the handler function (taking
  73  *                        one (void *), which is incidentally the udata).
  74  *                      o Third any flags.
  75  *
  76  * Note that you should ALWAYS format the msg_box() call like:
  77  *
  78  * msg_box(term, mem_list, flags,
  79  *         title, align,
  80  *         text,
  81  *         udata, M,
  82  *         label1, handler1, flags1,
  83  *         ...,
  84  *         labelM, handlerM, flagsM);
  85  *
  86  * ...no matter that it could fit on one line in case of a tiny message box. */
  87 struct dialog_data *
  88 msg_box(struct terminal *term, struct memory_list *mem_list,
  89         enum msgbox_flags flags, unsigned char *title, enum format_align align,
  90         unsigned char *text, void *udata, int buttons, ...);
  91
  92
  93 /* msg_text() is basically an equivalent to asprintf(), specifically to be used
  94  * inside of message boxes. Please always use msg_text() instead of asprintf()
  95  * in msg_box() parameters (ie. own format conversions can be introduced later
  96  * specifically crafted for message boxes, and so on).
  97  * The returned string is allocated and may be NULL!
  98  * This one automagically localizes the format string. The possible
  99  * additional parameters still need to be localized manually at the user's
 100  * side. */
 101 unsigned char *msg_text(struct terminal *term, unsigned char *format, ...);
 102
 103 /* A periodically refreshed message box with one OK button. The text in the
 104  * message box is updated using the get_info() function. If get_info() returns
 105  * NULL the message box is closed. */
 106 void
 107 refreshed_msg_box(struct terminal *term, enum msgbox_flags flags,
 108                   unsigned char *title, enum format_align align,
 109                   unsigned char *(get_info)(struct terminal *, void *),
 110                   void *data);
 111
 112 struct dialog_data *
 113 info_box(struct terminal *term, enum msgbox_flags flags,
 114          unsigned char *title, enum format_align align,
 115          unsigned char *text);
 116
 117
 118 #endif