.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2020 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc



.. _wx.RichMessageDialog:

==========================================================================================================================================
|phoenix_title|  **wx.RichMessageDialog**
==========================================================================================================================================

Extension of :ref:`wx.MessageDialog`  with additional functionality.          

This class adds the possibility of using a checkbox (that is especially useful for implementing the "Don't ask me again" kind of dialogs) and an extra explanatory text which is initially collapsed and not shown to the user but can be expanded to show more information. 

Notice that currently the native dialog is used only under MSW when using Vista or later Windows version. Elsewhere, or for older versions of Windows, a generic implementation which is less familiar to the users is used. Because of this it's recommended to use this class only if you do need its extra functionality and use :ref:`wx.MessageDialog`  which does have native implementation under all platforms otherwise. However if you do need to put e.g. a checkbox in a dialog, you should definitely consider using this class instead of using your own custom dialog because it will have much better appearance at least under recent Windows versions. 

To use this class, you need to create the dialog object and call :meth:`~wx.RichMessageDialog.ShowCheckBox`  and/or :meth:`~wx.RichMessageDialog.ShowDetailedText`  to configure its contents. Other than that, it is used in exactly the same way as :ref:`wx.MessageDialog`  and supports all the styles supported by it. In particular, :meth:`~wx.RichMessageDialog.ShowModal`  return value is the same as for :ref:`wx.MessageDialog`. The only difference is that you need to use :meth:`~wx.RichMessageDialog.IsCheckBoxChecked`  to examine the checkbox value if you had called :meth:`~wx.RichMessageDialog.ShowCheckBox`. 

Here is a simple example: ::

    def ShowDialog(self):

        if dont_show:
            return

        dlg = wx.RichMessageDialog(self, "Welcome to my wonderful program!")
        dlg.ShowCheckBox("Don't show welcome dialog again")
        dlg.ShowModal() # return value ignored as we have "Ok" only anyhow

        if dlg.IsCheckBoxChecked():
            # ... make sure we won't show it again the next time ...
            dont_show = True









         



.. versionadded:: 2.9.2 
    







.. seealso:: :ref:`MessageDialog Overview <messagedialog overview>`    







|

|class_hierarchy| Class Hierarchy
=================================

.. raw:: html

   <div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
   <img id="toggleBlock-trigger" src="_static/images/closed.png"/>
   Inheritance diagram for class <strong>RichMessageDialog</strong>:
   </div>
   <div id="toggleBlock-summary" style="display:block;"></div>
   <div id="toggleBlock-content" style="display:none;">
   <p class="graphviz">
   <center><img src="_static/images/inheritance/wx.RichMessageDialog_inheritance.png" alt="Inheritance diagram of RichMessageDialog" usemap="#dummy" class="inheritance"/></center>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.RichMessageDialog.html" title="wx.RichMessageDialog" alt="" coords="52,101,224,131"/> </map> 
   </p>
   </div>

|


|method_summary| Methods Summary
================================

================================================================================ ================================================================================
:meth:`~wx.RichMessageDialog.__init__`                                           Constructor specifying the rich message dialog properties.
:meth:`~wx.RichMessageDialog.GetCheckBoxText`                                    Retrieves the label for the checkbox.
:meth:`~wx.RichMessageDialog.GetClassDefaultAttributes`                          
:meth:`~wx.RichMessageDialog.GetDetailedText`                                    Retrieves the detailed text.
:meth:`~wx.RichMessageDialog.GetFooterIcon`                                      Retrieves the footer icon.
:meth:`~wx.RichMessageDialog.GetFooterText`                                      Retrieves the footer text.
:meth:`~wx.RichMessageDialog.IsCheckBoxChecked`                                  Retrieves the state of the checkbox.
:meth:`~wx.RichMessageDialog.SetFooterIcon`                                      Specify the footer icon set together with the footer text.
:meth:`~wx.RichMessageDialog.SetFooterText`                                      Shows or hides a footer text that is used at the bottom of the dialog together with an optional icon.
:meth:`~wx.RichMessageDialog.ShowCheckBox`                                       Shows a checkbox with a given label or hides it.
:meth:`~wx.RichMessageDialog.ShowDetailedText`                                   Shows or hides a detailed text and an expander that is used to show or hide the detailed text.
:meth:`~wx.RichMessageDialog.ShowModal`                                          Shows the dialog, returning one of ``wx.ID_OK``, ``wx.ID_CANCEL``, ``wx.ID_YES``, ``wx.ID_NO``.
================================================================================ ================================================================================


|


|property_summary| Properties Summary
=====================================

================================================================================ ================================================================================
:attr:`~wx.RichMessageDialog.CheckBoxText`                                       See :meth:`~wx.RichMessageDialog.GetCheckBoxText`
:attr:`~wx.RichMessageDialog.DetailedText`                                       See :meth:`~wx.RichMessageDialog.GetDetailedText`
:attr:`~wx.RichMessageDialog.FooterIcon`                                         See :meth:`~wx.RichMessageDialog.GetFooterIcon` and :meth:`~wx.RichMessageDialog.SetFooterIcon`
:attr:`~wx.RichMessageDialog.FooterText`                                         See :meth:`~wx.RichMessageDialog.GetFooterText` and :meth:`~wx.RichMessageDialog.SetFooterText`
================================================================================ ================================================================================


|


|api| Class API
===============


.. class:: wx.RichMessageDialog(GenericMessageDialog)

   **Possible constructors**::

       RichMessageDialog(parent, message, caption=MessageBoxCaptionStr,
                         style=OK|CENTRE)
       
   
   Extension of MessageDialog with additional functionality.



   .. method:: __init__(self, parent, message, caption=MessageBoxCaptionStr, style=OK|CENTRE)

      Constructor specifying the rich message dialog properties.                  

      Works just like the constructor for :ref:`wx.MessageDialog`.                  


      :param `parent`: 
      :type `parent`: wx.Window
      :param `message`: 
      :type `message`: string
      :param `caption`: 
      :type `caption`: string
      :param `style`: 
      :type `style`: long







   .. method:: GetCheckBoxText(self)

      Retrieves the label for the checkbox.                  

                

      :rtype: `string`







      :returns: 

         The label for the checkbox, will be the empty string if no checkbox is used.   








   .. staticmethod:: GetClassDefaultAttributes(variant=WINDOW_VARIANT_NORMAL)




      :param `variant`: 
      :type `variant`: wx.WindowVariant




      :rtype: :ref:`wx.VisualAttributes`








   .. method:: GetDetailedText(self)

      Retrieves the detailed text.                  

                

      :rtype: `string`







      :returns: 

         The detailed text or empty if detailed text is not used.   








   .. method:: GetFooterIcon(self)

      Retrieves the footer icon.                  

                

      :rtype: `int`







      :returns: 

         The footer icon or 0 if footer icon is not used.  







      .. versionadded:: 4.1/wxWidgets-3.1.1  
     







      .. seealso:: :meth:`SetFooterIcon`   








   .. method:: GetFooterText(self)

      Retrieves the footer text.                  

                

      :rtype: `string`







      :returns: 

         The footer text or empty if footer text is not used.  







      .. versionadded:: 4.1/wxWidgets-3.1.1  
     








   .. method:: IsCheckBoxChecked(self)

      Retrieves the state of the checkbox.                  

      If this method is called before showing the dialog, the initial value of the checkbox, as set by :meth:`ShowCheckBox`   is used. If it is called after calling :meth:`wx.Dialog.ShowModal` , the value set by the user is returned. 

                

      :rtype: `bool`







      :returns: 

         ``True`` if the checkbox is checked or ``False`` if not.   








   .. method:: SetFooterIcon(self, icon)

      Specify the footer icon set together with the footer text.                  

      Valid values are  ``ICON_INFORMATION`` ,   ``ICON_WARNING`` ,   ``ICON_AUTH_NEEDED``   and   ``ICON_ERROR``   (notice that   ``ICON_QUESTION``   is not allowed here). 

                


      :param `icon`: 
      :type `icon`: int






      .. versionadded:: 4.1/wxWidgets-3.1.1  
     







      .. seealso:: :meth:`GetFooterIcon` , :meth:`SetFooterText`   








   .. method:: SetFooterText(self, footerText)

      Shows or hides a footer text that is used at the bottom of the dialog together with an optional icon.                  




      :param `footerText`: The footer text if empty no footer text will be used.  
      :type `footerText`: string




                  



      .. versionadded:: 4.1/wxWidgets-3.1.1  
     







      .. seealso:: :meth:`SetFooterIcon` , :meth:`GetFooterText`   








   .. method:: ShowCheckBox(self, checkBoxText, checked=False)

      Shows a checkbox with a given label or hides it.                  




      :param `checkBoxText`: If the parameter is non-empty a checkbox will be shown with that label, otherwise it will be hidden.   
      :type `checkBoxText`: string
      :param `checked`: The initial state of the checkbox.   
      :type `checked`: bool






                  





   .. method:: ShowDetailedText(self, detailedText)

      Shows or hides a detailed text and an expander that is used to show or hide the detailed text.                  




      :param `detailedText`: The detailed text that can be expanded when the dialog is shown, if empty no detailed text will be used.   
      :type `detailedText`: string




                  





   .. method:: ShowModal(self)

      Shows the dialog, returning one of ``wx.ID_OK``, ``wx.ID_CANCEL``, ``wx.ID_YES``, ``wx.ID_NO``.                  

      :meth:`IsCheckBoxChecked`   can be called afterwards to retrieve the value of the check box if one was used.                  

      :rtype: `int`








   .. attribute:: CheckBoxText

      See :meth:`~wx.RichMessageDialog.GetCheckBoxText`


   .. attribute:: DetailedText

      See :meth:`~wx.RichMessageDialog.GetDetailedText`


   .. attribute:: FooterIcon

      See :meth:`~wx.RichMessageDialog.GetFooterIcon` and :meth:`~wx.RichMessageDialog.SetFooterIcon`


   .. attribute:: FooterText

      See :meth:`~wx.RichMessageDialog.GetFooterText` and :meth:`~wx.RichMessageDialog.SetFooterText`

