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 variadic 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  *              Each triple should be wrapped in the MSG_BOX_BUTTON
  76  *              macro, which converts the values to the correct types.
  77  *              (The compiler can't do that on its own for variadic
  78  *              arguments.)
  79  *
  80  * Note that you should ALWAYS format the msg_box() call like:
  81  *
  82  * msg_box(term, mem_list, flags,
  83  *         title, align,
  84  *         text,
  85  *         udata, M,
  86  *         MSG_BOX_BUTTON(label1, handler1, flags1),
  87  *         ...,
  88  *         MSG_BOX_BUTTON(labelM, handlerM, flagsM));
  89  *
  90  * ...no matter that it could fit on one line in case of a tiny message box. */
  91 struct dialog_data *
  92 msg_box(struct terminal *term, struct memory_list *mem_list,
  93         enum msgbox_flags flags, unsigned char *title, enum format_align align,
  94         unsigned char *text, void *udata, int buttons, ...);
  95
  96 /* Cast @value to @type and warn if the conversion is suspicious.
  97  * If @value has side effects, this does them only once.
  98  * The expression used here is intended to be standard C, but it is
  99  * somewhat tricky.  If it causes trouble on some compiler, you can
 100  * #ifdef an alternative definition that skips the type check.  */
 101 #define MSG_BOX_CAST(type, value) \
 102         (((void) sizeof(((int (*)(type)) 0)(value))), (type) (value))
 103
 104 /* A button in the variadic arguments of msg_box().
 105  * This macro expands into three arguments.  */
 106 #define MSG_BOX_BUTTON(label, handler, flags) \
 107         MSG_BOX_CAST(const unsigned char *, label), \
 108         MSG_BOX_CAST(done_handler_T *, handler), \
 109         MSG_BOX_CAST(int, flags)
 110
 111
 112 /* msg_text() is basically an equivalent to asprintf(), specifically to be used
 113  * inside of message boxes. Please always use msg_text() instead of asprintf()
 114  * in msg_box() parameters (ie. own format conversions can be introduced later
 115  * specifically crafted for message boxes, and so on).
 116  * The returned string is allocated and may be NULL!
 117  * This one automagically localizes the format string. The possible
 118  * additional parameters still need to be localized manually at the user's
 119  * side. */
 120 unsigned char *msg_text(struct terminal *term, unsigned char *format, ...);
 121
 122 /* A periodically refreshed message box with one OK button. The text in the
 123  * message box is updated using the get_info() function. If get_info() returns
 124  * NULL the message box is closed. */
 125 void
 126 refreshed_msg_box(struct terminal *term, enum msgbox_flags flags,
 127                   unsigned char *title, enum format_align align,
 128                   unsigned char *(get_info)(struct terminal *, void *),
 129                   void *data);
 130
 131 struct dialog_data *
 132 info_box(struct terminal *term, enum msgbox_flags flags,
 133          unsigned char *title, enum format_align align,
 134          unsigned char *text);
 135
 136
 137 #endif