================
Dialog (hwx.gui)
================

A top-level window mostly used for short-term tasks and brief communications
with the user.

Inherits:
  - :ref:`DialogBase (hwx.gui)`

----------
Properties
----------

  +----------------+
  | closeOnEscape_ |
  +----------------+

--------------
Public Methods
--------------

  +------------------------------------------------------------------+
  | classmethod get_ (cls)                                           |
  +------------------------------------------------------------------+
  | accept_ (self, returnValue)                                      |
  +------------------------------------------------------------------+
  | createContents_ (self)                                           |
  +------------------------------------------------------------------+
  | exec_ (self)                                                     |
  +------------------------------------------------------------------+
  | positionUnder_ (self, relativeTo, checkWasMoved=True, xoffset=0) |
  +------------------------------------------------------------------+
  | reject_ (self)                                                   |
  +------------------------------------------------------------------+
  | resize_ (self, width, height)                                    |
  +------------------------------------------------------------------+
  | show_ (self)                                                     |
  +------------------------------------------------------------------+

----------------
Property Details
----------------

.. _closeOnEscape:
.. property:: closeOnEscape

The behavior when the user presses the Esc key in a dialog.

--------------
Method Details
--------------

.. _get:
.. classmethod:: get(cls)

Get singleton when dialog is implemented as a subclass

Used by associated Button/SpriteActions.

.. _accept:
.. method:: accept(self, returnValue)

Close the dialog and returnValue from exec.

.. _createContents:
.. method:: createContents(self)

To be implemented in derived class.

.. _exec:
.. method:: exec(self)

Show as a model dialog, blocking code execution until it is closed.

This is typically used to get user input before continuing.
Dialog code returns the input from exec by calling self.accept(value).

:returns: The accepted value or None if the dialog is closed in any other way.


.. _positionUnder:
.. method:: positionUnder(self, relativeTo, checkWasMoved=True, xoffset=0)

Positions the dialog under or over the relataveTo widget.

:param relativeTo: The widget to position relative to.
:type relativeTo: Widget
:param checkWasMoved: Determines whether to check if widget is moved or not.
:type checkWasMoved: bool
:param xoffset: The offset value for the widget for x-axis.
:type xoffset: int


.. _reject:
.. method:: reject(self)

Syntactic sugar to close the exec dialog without accepting a value.
None is returned from exec.

.. _resize:
.. method:: resize(self, width, height)

Resize width/height of dialog.

This does not prevent the user from manually resizing like setting the
width/height does.

.. _show:
.. method:: show(self)

Shows the dialog and continues with script execution.