mirror of
https://github.com/rkd77/elinks.git
synced 2025-01-03 14:57:44 -05:00
BFU: Document additional data in struct dialog
This commit is contained in:
parent
a1c5fe518b
commit
dd608c500b
@ -57,17 +57,68 @@ struct dialog {
|
||||
|
||||
struct dialog_layout layout;
|
||||
|
||||
/** How many widgets have been added to this dialog.
|
||||
* The #widgets array may be larger than this if some
|
||||
* of the intended widgets have not yet been added. */
|
||||
int number_of_widgets;
|
||||
|
||||
struct widget widgets[1]; /* must be at end of struct */
|
||||
|
||||
/* There may be additional data after widgets[]. The size and
|
||||
* format of the additional data is specific to each dialog.
|
||||
* Dialogs typically place the buffer of each WIDGET_FIELD
|
||||
* widget somewhere in this additional-data area so that the
|
||||
* buffer need not be allocated and freed separately.
|
||||
*
|
||||
* When constructing a dialog, give the size of the additional
|
||||
* data as a parameter to sizeof_dialog() and calloc_dialog().
|
||||
* Then, use get_dialog_offset() to get the address of the
|
||||
* additional data. */
|
||||
};
|
||||
|
||||
/* Allocate a struct dialog for n - 1 widgets, one is already reserved in struct.
|
||||
* add_size bytes will be added. */
|
||||
/** Gets the amount of memory needed for a dialog.
|
||||
*
|
||||
* @param n
|
||||
* How many widgets there will be in the dialog.
|
||||
* @param add_size
|
||||
* The size of the additional data, in bytes.
|
||||
*
|
||||
* @return
|
||||
* The total amount of memory needed for struct dialog, the widgets,
|
||||
* and the additional data. This however does not include struct
|
||||
* dialog_data.
|
||||
*
|
||||
* struct dialog already reserves memory for one widget. */
|
||||
#define sizeof_dialog(n, add_size) \
|
||||
(sizeof(struct dialog) + ((n) - 1) * sizeof(struct widget) + (add_size))
|
||||
|
||||
/** Allocates and clears memory for a dialog.
|
||||
*
|
||||
* @param n
|
||||
* How many widgets there will be in the dialog.
|
||||
* @param add_size
|
||||
* The size of the additional data, in bytes.
|
||||
*
|
||||
* @return
|
||||
* struct dialog *; or NULL if out of memory.
|
||||
*
|
||||
* This macro sets dialog.number_of_widgets = 0.
|
||||
* The caller can then add widgets to the dialog
|
||||
* until dialog.number_of_widgets reaches @a n. */
|
||||
#define calloc_dialog(n, add_size) ((struct dialog *) mem_calloc(1, sizeof_dialog(n, add_size)))
|
||||
|
||||
/** Gets the address of the additional data of a dialog.
|
||||
*
|
||||
* @param dlg
|
||||
* struct dialog *dlg; the dialog that carries the additional data.
|
||||
* @param n
|
||||
* For how many widgets the dialog was allocated; i.e. the
|
||||
* @c n parameter of sizeof_dialog() and calloc_dialog().
|
||||
* This macro does not read dialog.number_of_widgets because
|
||||
* that is typically still zero when this macro is used.
|
||||
*
|
||||
* @return
|
||||
* The address of the additional data. */
|
||||
#define get_dialog_offset(dlg, n) \
|
||||
(((unsigned char *) dlg) + sizeof_dialog(n, 0))
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user