## st-dialog

st-dialog — functions for outputting messages and displaying simple dialogs.

## Synopsis

    void        st_notice                       (const char *format,
                                                 ...);
    void        st_info_dialog                  (const char *primary,
                                                 const char *format,
                                                 ...);
    void        st_error_dialog                 (const char *primary,
                                                 const char *format,
                                                 ...);
    char*       st_search_dialog                (void);
    gboolean    st_auth_dialog                  (const char *default_name,
                                                 const char *default_password,
                                                 char **name,
                                                 char **password,
                                                 const char *primary,
                                                 const char *format,
                                                 ...);
    char*       st_dialog_normalize             (const char *str);
    void        st_warning                      (const char *format,
                                                 ...);
    void        st_error                        (const char *format,
                                                 ...);
    int         st_question                     (const char *format,
                                                 ...);
    char*       st_prompt                       (gboolean hidden,
                                                 const char *init,
                                                 const char *format,
                                                 ...);

## Description

These functions provide support for outputting messages to the console as well as displaying graphical message dialogs.

## Details

### st_notice ()

    void        st_notice                       (const char *format,
                                                 ...);

Outputs a formatted streamtuner notice to the standard error output.

If you need to output a notice regarding a specific handler, use `st_handler_notice()` instead of this function.

`format` : | the message format. See the `printf()` documentation.
`...` : | the parameters to insert into the format string.

### st_info_dialog ()

    void        st_info_dialog                  (const char *primary,
                                                 const char *format,
                                                 ...);

Displays an informational dialog.

`primary` : | the primary text, or `NULL`.
`format` : | the secondary text format, or `NULL`. See the `printf()` documentation.
`...` : | the parameters to insert into the format string.

### st_error_dialog ()

    void        st_error_dialog                 (const char *primary,
                                                 const char *format,
                                                 ...);

Displays an error dialog.

`primary` : | the primary text, or `NULL`.
`format` : | the secondary text format, or `NULL`. See the `printf()` documentation.
`...` : | the parameters to insert into the format string.

### st_search_dialog ()

    char*       st_search_dialog                (void);

Prompts the user for a search string.

Returns : | a search string which should be freed after use, or `NULL` if the user pressed the cancel button.

### st_auth_dialog ()

    gboolean    st_auth_dialog                  (const char *default_name,
                                                 const char *default_password,
                                                 char **name,
                                                 char **password,
                                                 const char *primary,
                                                 const char *format,
                                                 ...);

Prompts the user for a name and password. The name and password entries will be initialized to `default_name` and `default_password`, if provided.

The entered name and password will be stored in `name` and `password`, and should be freed when no longer needed. If `name` is `NULL`, the name entry will not be made sensitive.

`default_name` : | a default name, or `NULL`.
`default_password` : | a default password, or `NULL`.
`name` : | a location to return the entered name, or `NULL`.
`password` : | a location to return the entered password.
`primary` : | the primary text, or `NULL`.
`format` : | the secondary text format, or `NULL`. See the `printf()` documentation.
`...` : | the parameters to insert into the format string.
Returns : | `TRUE` if the user pressed the "Authenticate" button, `FALSE` otherwise. If `FALSE` is returned, `name` and `password` will not be set.

### st_dialog_normalize ()

    char*       st_dialog_normalize             (const char *str);

Normalizes a string so that it can be used stand-alone as the secondary string of a dialog.

Normalization will remove trailing newlines and convert the string to a sentence.

`str` : | a string to normalize.
Returns : | a normalized string, which should be freed after use.

### st_warning ()

    void        st_warning                      (const char *format,
                                                 ...);

### Warning

`st_warning` is deprecated and should not be used in newly-written code.

`format` : |
`...` : |

### st_error ()

    void        st_error                        (const char *format,
                                                 ...);

### Warning

`st_error` is deprecated and should not be used in newly-written code.

`format` : |
`...` : |

### st_question ()

    int         st_question                     (const char *format,
                                                 ...);

### Warning

`st_question` is deprecated and should not be used in newly-written code.

`format` : |
`...` : |
Returns : |

### st_prompt ()

    char*       st_prompt                       (gboolean hidden,
                                                 const char *init,
                                                 const char *format,
                                                 ...);

### Warning

`st_prompt` is deprecated and should not be used in newly-written code.

`hidden` : |
`init` : |
`format` : |
`...` : |
Returns : |

## See Also

`st_handler_notice()`