# module Alerts

This module defines functions that display various commonly-used types of modal dialog containing a textual message.

## Alert kinds

The `kind` parameter in the following functions determines the appearance of the dialog. It may take the following values:

> `'stop'`
>   Used for displaying an error message or other condition which prevents an operation from being completed.
> `'caution'`
>   Used for warning the user when an operation could cause loss of data or other undesirable effects.
> `'note'`
>   Used for presenting an informational message to the user.
> `'query'`
>   Used for requesting information from the user.

Some platforms may not display all of these in a unique way.

## Functions

### Low-level alert functions

`alert(kind, message, ok_label = "OK")`
  Displays an alert box with one button, which is the default button. Does not return a value.

`alert2(kind,` `message``, yes_label = "Yes", no_label = "No",`
`default = 1, cancel = 0)`
  Displays an alert box with two buttons. Returns 1 if the "yes" button is pressed, 0 if the "no" button is pressed. The `default` and `cancel` parameters specify which buttons, if any, are activated by the standard keyboard equivalents, and take the values `1`, `0` or `None`.

`alert3(kind, message, yes_label = "Yes", no_label = "No",
other_label = "Cancel",` `default = 1, cancel = -1``)`
  Displays an alert box with three buttons. Returns 1 if the "yes" button is pressed, 0 if the "no" button is pressed, and -1 if the "other" button is pressed. The `default` and `cancel` parameters specify which buttons, if any, are activated by the standard keyboard equivalents, and take the values `1`, `0`, `-1` or `None`.

In addition to the parameters listed above, these functions also accept the following optional parameters:

> `width`
>   The overall width of the alert box.
> `lines`
>   The number of lines to allow for in the text area of the alert box.

These parameters are hints only; platforms are free to ignore them and calculate the size of the alert box from the text provided.

### High-level alert functions

The following functions provide shorthands for calling the above functions with certain common combinations of parameters.

`note_alert(message,` ...`)`
  Equivalent to `alert('note', message,` ...`)`.

`stop_alert(message,` ...`)`
  Equivalent to `alert('stop', message,` ...`)`.

`ask(message,` ...`)`
  Equivalent to `alert2('query', message,` ...`)`.

`confirm(message,` ...`)`
  Equivalent to `alert2('caution', message,` ...`)`.

`ask_or_cancel(message,` ...`)`
  Equivalent to `alert3('query', message,` ...`)`.

`confirm_or_cancel(message,` ...`)`
  Equivalent to `alert3('caution', message,` ...`)`.

---