int dialog_run

(char* msg, int visual, int linear, char* data,
size_t len)

Issue a dialogue box.

Documentation

Issue a dialogue box.

This function issues and handles an interactive, full-screen dialogue box for data-entry purposes. The user is presented with either a full-screen (visual) interface, or the traditional menu-driven environment. This depends on the user's personal settings.

Parameters:

msg - The name of a message block file to open. This is used to obtain the dialogue templates, custom help strings, and other prompts. It should be supplied as a basename (no directories), and without the .mbk extension. In other words, just like the string you pass to msg_open().
visual - The prompt number of the full-screen template for this dialogue. This is almost exactly the same as any old ANSI prompt, with one addition: it allows certain escape directives to specify the position and format of entry fields, buttons, and other controls. For the nature of those controls, please refer to the Template directives section below.
linear - The base prompt number of the linear, traditional data entry template. This allows the same template directives as above, but the controls are rendered in a different way.
data - A string containing the default values of the fields specified in the template, in the order specified in the template. Upon exit, the same string will hold the contents of the same fields, as modified by the user (or the default, if the fields were not modified). A dialogue exit code or the name of the button that terminated the dialogue is also returned. The format of the string and how to parse it are described elsewhere in this section of documentation. Look at it for fuller instructions on how to do it.
len - The size of data. No results exceeding this size will be read from the dialogue. Make sure there's enough space!

Returns:

A result compatible with that of the runmodule() command, or -1 if an error occurred in preparing for data entry.

Alphabetic index