Dialog Functions
================

In addition to the TaskDialog class, there are convenience functions that wrap
its functionality into a single call. Additionally, if the TaskDialog is not
available on the system, the functions will display an alternative dialog box
(although with not as much detail) so that the calling application does not break.

.. currentmodule:: curtains

.. function:: save_or_not_dialog([show_footer[, literature[, parenthwnd]]])

    Display a dialog prompting the user to save changes in an application. The
    dialog consists of ``Save``, ``Don't Save`` and ``Cancel`` buttons.

    :param show_footer: if this is set to True, a footer is displayed at the
                        bottom of the dialog with a warning icon.

    :param literature: a dictionary with values describing the text that the
                       dialog displays. The supported keys and their default
                       values are:


                       ``title`` - Window title of the dialog. Default to "Message"

                       ``heading`` - Defaults to "You have unsaved changes"

                       ``content`` - Defaults to "Do you want to save those changes before you continue?"

                       ``footer`` - Defaults to "Your changes will be lost if you don't save them."

                       ``save`` - Label of the save button. Defaults to "Save"

                       ``dontsave`` - Label of the don't save button. Defaults to "Don't Save".

    :type literature: python dictionary

    :returns: Either :data:`SAVE`, :data:`DONTSAVE` or :data:`CANCEL` indicating
              which button the user pressed.


.. function:: save_or_not_dialog_wx([show_footer[, literature[, parent]]])

    Display a dialog prompting the user to save changes in a wxPython
    application. The dialog consists of ``Save``, ``Don't Save`` and ``Cancel``
    buttons.

    :param parent: The parent window of the dialog.
    :type parent: wx.TopLevelWindow or None

    Calling this dialog with a parent has the side-effect of invoke the Show()
    method on parent, as well as making the dialog modal to the parent window.
    The dialog will also take the parent window's title if no title is supplied
    with ``literature``.

    See :func:`save_or_not_dialog` for other parameters and return type.


.. data:: SAVE

    Constant returned when the user presses the designated save button in a
    save/don't save dialog.

.. data:: DONTSAVE

    Constant returned when the user presses the dontsave button in a save/don't
    save dialog.

.. data:: CANCEL

    Constant returned from a dialog function when a user cancels the dialog.