Dialog Boxes

FUNCTIONS

  void  error(App *app, char *message);

  void  ask_ok(App *app, char *title, char *message);
  int   ask_ok_cancel(App *app, char *title, char *question);
  int   ask_yes_no(App *app, char *title, char *question);
  int   ask_yes_no_cancel(App *app, char *title, char *question);

  char *ask_string(App *app, char *title, char *question,
                       char *default_answer);
  char *ask_file_open(App *app, char *title, char *message,
                          char *path);
  char *ask_file_save(App *app, char *title, char *message,
                          char *path);

CONSTANTS

  enum {
    CANCEL = -1,
    NO     =  0,
    YES    =  1
  };

NOTES

The error function displays the message string in a modal message window before terminating the application.

The rest of the functions which accept a title string parameter, display a modal dialog box with the given title string showing in the title bar.

The ask_ok function displays the message string in a modal window with an "OK" button which the user can select to dismiss the window.

The ask_ok_cancel function displays a modal window with a question, and returns YES if the user clicks the "OK" button, and CANCEL if the "Cancel" button is used to dismiss the window.

The ask_yes_no function displays the question string in a modal window with two buttons, "Yes" and "No". The user may select either one to dismiss the window. If the user selects "Yes", the function returns YES; if the user selects "No" the function returns NO.

The ask_yes_no_cancel function operates the same way except it has another button "Cancel" which, if selected, will cause the function to return CANCEL.

The ask_string function displays the question string in a modal window with the specified title, which also has a text field into which the user can type a string. The text field is initially loaded with the default_answer. Space is allocated for the string using alloc and then returned to the programmer by the function (use free to free the returned string). If the user selects the "Cancel" button in this window, the function will instead return NULL.

The ask_file_open function displays a modal window which can be used to select a file from the file system. The path string is loaded into the filename text field if this is available. The function returns the complete file pathname as a string, or NULL if the user cancels the operation. The returned string should be freed using free when it is no longer needed.

The ask_file_save function is similar, except that it is used when saving a file, and the window may appear differently to signal that fact. It will warn the user if a selected file already exists to confirm overwriting the file is allowed. The returned file path string should be freed using free when it is no longer needed.