<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<refentry id="class-gtkmessagedialog">
  <refnamediv>
    <refname>gtk.MessageDialog</refname>
    <refpurpose>a convenient message window</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.MessageDialog</classname></ooclass>
      <ooclass><classname><link
linkend="class-gtkdialog">gtk.Dialog</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-gtkmessagedialog">gtk.MessageDialog</link></methodname>
	<methodparam><parameter
		       role="keyword">parent</parameter><initializer>None</initializer></methodparam>
	<methodparam><parameter
		       role="keyword">flags</parameter><initializer>0</initializer></methodparam>
	<methodparam><parameter
		       role="keyword">type</parameter><initializer><literal>gtk.MESSAGE_INFO</literal></initializer></methodparam>
	<methodparam><parameter
		       role="keyword">buttons</parameter><initializer><literal>gtk.BUTTONS_NONE</literal></initializer></methodparam>
	<methodparam><parameter
		       role="keyword">message_format</parameter><initializer>None</initializer></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkmessagedialog--set-markup">set_markup</link></methodname>
	<methodparam><parameter
		       role="keyword">str</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkmessagedialog--format-secondary-text">format_secondary_text</link></methodname>
	<methodparam><parameter
		       role="keyword">message_format</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkmessagedialog--format-secondary-markup">format_secondary_markup</link></methodname>
	<methodparam><parameter
		       role="keyword">message_format</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkmessagedialog--set-image">set_image</link></methodname>
        <methodparam><parameter role="keyword">image</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkmessagedialog--get-image">get_image</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkmessagedialog--get-message-area">get_message_area</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtkobject">gtk.Object</link>
    +-- <link linkend="class-gtkwidget">gtk.Widget</link>
      +-- <link linkend="class-gtkcontainer">gtk.Container</link>
        +-- <link linkend="class-gtkbin">gtk.Bin</link>
          +-- <link linkend="class-gtkwindow">gtk.Window</link>
            +-- <link linkend="class-gtkdialog">gtk.Dialog</link>
              +-- <link linkend="class-gtkmessagedialog">gtk.MessageDialog</link>
</synopsis>

  </refsect1>
  
  <refsect1>
		<title>Implemented Interfaces</title>
		<para>
			<link linkend="class-gtkmessagedialog"><classname>gtk.MessageDialog</classname></link>
			implements 
			<link linkend="class-gtkbuildable"><classname>gtk.Buildable</classname></link>
		</para>
	</refsect1>


  <refsect1 id="properties-gtkmessagedialog">
    <title>gtk.MessageDialog Properties</title>

    <para><link linkend="properties-gtkobject">gtk.Object Properties</link></para>
    <para><link linkend="properties-gtkwidget">gtk.Widget Properties</link></para>
    <para><link linkend="properties-gtkcontainer">gtk.Container Properties</link></para>
    <para><link linkend="properties-gtkwindow">gtk.Window Properties</link></para>
    <para><link linkend="properties-gtkdialog">gtk.Dialog Properties</link></para>

    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
	<tgroup cols="3">
	  <colspec column="1" colwidth="1in"/>
	  <colspec column="2" colwidth="1in"/>
	  <colspec column="3" colwidth="4in"/>
	  <tbody>

	    <row valign="top">
	      <entry>"buttons"</entry>
              <entry>Write-Construct</entry>
	      <entry>The buttons shown in the message dialog. One of the
<xref linkend="gtk-buttons-type-constants"
endterm="gtk-buttons-type-constants-title"></xref>:
<literal>gtk.BUTTONS_NONE</literal>,
<literal>gtk.BUTTONS_OK</literal>,
<literal>gtk.BUTTONS_CLOSE</literal>,
<literal>gtk.BUTTONS_CANCEL</literal>,
<literal>gtk.BUTTONS_YES_NO</literal>,
<literal>gtk.BUTTONS_OK_CANCEL</literal>. Default value:
<literal>gtk.BUTTONS_NONE</literal></entry>
	    </row>

	    <row valign="top">
	      <entry>"image"</entry>
	      <entry>Read-Write</entry>
	      <entry>The image for this dialog. Available in GTK+
	      2.10.</entry>
	    </row>

	    <row valign="top">
	      <entry>"message-area"</entry>
	      <entry>Read</entry>
	      <entry>The <link linkend="class-gtkvbox"><classname>gtk.VBox</classname></link>
        that corresponds to the message area of this dialog. Available in GTK+ 2.22.</entry>
	    </row>

	    <row valign="top">
	      <entry>"message-type"</entry>
	      <entry>Read-Write-Construct</entry>
	      <entry>The type of message. One of the
<xref linkend="gtk-message-type-constants"
endterm="gtk-message-type-constants-title"></xref>:
<literal>gtk.MESSAGE_INFO</literal>, <literal>gtk.MESSAGE_WARNING</literal>,
<literal>gtk.MESSAGE_QUESTION</literal> or
<literal>gtk.MESSAGE_ERROR</literal>. Default value:
<literal>gtk.MESSAGE_INFO</literal></entry>
	    </row>

	    <row valign="top">
	      <entry>"secondary-text"</entry>
	      <entry>Read-Write</entry>
	      <entry>The secondary text of the message dialog. Default
	      value: <literal>None</literal>. Available in GTK+
	      2.10.</entry>
	    </row>

	    <row valign="top">
	      <entry>"secondary-use-markup"</entry>
	      <entry>Read-Write</entry>
	      <entry>If <literal>True</literal> the secondary text of the
	      dialog includes Pango markup. See the <link
	      linkend="function-pango--parse-markup"><function>pango.parse_markup</function>()</link>
	      function.  Default value: <literal>False</literal>. Available
	      in GTK+ 2.10.</entry>
	    </row>

	    <row valign="top">
	      <entry>"text"</entry>
	      <entry>Read-Write</entry>
	      <entry>The primary text of the message dialog. If the dialog
	      has a secondary text, this will appear as the title. Default
	      value: <literal>None</literal>. Available in GTK+
	      2.10.</entry>
	    </row>

	    <row valign="top">
	      <entry>"use-markup"</entry>
	      <entry>Read-Write</entry>
	      <entry>If <literal>True</literal> the primary text of the
	      dialog includes Pango markup. See the <link
	      linkend="function-pango--parse-markup"><function>pango.parse_markup</function>()</link>
	      function. Default value: <literal>False</literal>. Available
	      in GTK+ 2.10.</entry>
	    </row>

	  </tbody>
	</tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1 id="style-properties-gtkmessagedialog">
    <title>gtk.MessageDialog Style Properties</title>

    <para><link linkend="style-properties-gtkwidget">gtk.Widget Style Properties</link></para>
    <para><link linkend="style-properties-gtkdialog">gtk.Dialog Style Properties</link></para>

    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
	<tgroup cols="3">
	  <colspec column="1" colwidth="1in"/>
	  <colspec column="2" colwidth="1in"/>
	  <colspec column="3" colwidth="4in"/>
	  <tbody>

	    <row valign="top">
	      <entry>"message-border"</entry>
	      <entry>Read-Write</entry>
	      <entry>The width of border around the label and image in the
message dialog. Allowed values: >= 0. Default value: 12.</entry>
	    </row>

        <row valign="top">
          <entry>"use-separator"</entry>
          <entry>Read</entry>
          <entry>If <literal>True</literal> draw a separator line between
          the message label and the buttons in the dialog.  This property is
          available in GTK+ 2.4 and above.</entry>
        </row>

	  </tbody>
	</tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1>
    <title>Attributes</title>

    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
	<tgroup cols="3">
	<?dbhtml cellpadding="5"?>
	  <colspec column="1" colwidth="1in"/>
	  <colspec column="2" colwidth="1in"/>
	  <colspec column="3" colwidth="4in"/>
	  <tbody>

	    <row valign="top">
	      <entry>"image"</entry>
	      <entry>Read</entry>
	      <entry>The stock ID image</entry>
	    </row>

	    <row valign="top">
	      <entry>"label"</entry>
	      <entry>Read</entry>
	      <entry>The label widget that contains the message
text.</entry>
	    </row>

	</tbody>
      </tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1 id="signal-prototypes-gtkmessagedialog">
    <title>gtk.MessageDialog Signal Prototypes</title>

    <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkobject">gtk.Object Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkwidget">gtk.Widget Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkcontainer">gtk.Container Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkwindow">gtk.Window Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkdialog">gtk.Dialog Signal Prototypes</link></para>
  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>The <link
linkend="class-gtkmessagedialog"><classname>gtk.MessageDialog</classname></link> 
presents a dialog with an image representing the type of message (Error,
Question, etc.) alongside some message text. It's simply a convenience
widget; you could construct the equivalent of <link
linkend="class-gtkmessagedialog"><classname>gtk.MessageDialog</classname></link> 
from <link
linkend="class-gtkdialog"><classname>gtk.Dialog</classname></link> without
too much effort, but <link
linkend="class-gtkmessagedialog"><classname>gtk.MessageDialog</classname></link> 
saves time.</para>

    <para>The <link
linkend="class-gtkmessagedialog"><classname>gtk.MessageDialog</classname></link>
types are listed in the <xref linkend="gtk-message-type-constants"
endterm="gtk-message-type-constants-title"></xref>.</para>

    <para>A selection of predefined button sets is available for use in a
message dialog. See the <xref linkend="gtk-buttons-type-constants"
endterm="gtk-buttons-type-constants-title"></xref>.</para>

    <para>See the <link
linkend="class-gtkdialog"><classname>gtk.Dialog</classname></link> reference
page for additional methods to be used with the <link
linkend="class-gtkmessagedialog"><classname>gtk.MessageDialog</classname></link>.</para>

  </refsect1>

  <refsect1 id="constructor-gtkmessagedialog">
    <title>Constructor</title>

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.MessageDialog</methodname>
	<methodparam><parameter
		       role="keyword">parent</parameter><initializer>None</initializer></methodparam>
	<methodparam><parameter
		       role="keyword">flags</parameter><initializer>0</initializer></methodparam>
	<methodparam><parameter
		       role="keyword">type</parameter><initializer><literal>gtk.MESSAGE_INFO</literal></initializer></methodparam>
    <methodparam><parameter
		   role="keyword">buttons</parameter><initializer><literal>gtk.BUTTONS_NONE</literal></initializer></methodparam>
    <methodparam><parameter
		   role="keyword">message_format</parameter><initializer>None</initializer></methodparam> 
</constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><parameter role="keyword">parent</parameter>&nbsp;:</term>
	<listitem><simpara>the transient parent, or None if
none</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter role="keyword">flags</parameter>&nbsp;:</term>
	<listitem><simpara>the dialog flags - a combination of:
<literal>gtk.DIALOG_MODAL</literal>,
<literal>gtk.DIALOG_DESTROY_WITH_PARENT</literal> or 0 for no
flags</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter role="keyword">type</parameter>&nbsp;:</term>
	<listitem><simpara>the type of message:
<literal>gtk.MESSAGE_INFO</literal>, <literal>gtk.MESSAGE_WARNING</literal>,
<literal>gtk.MESSAGE_QUESTION</literal> or
<literal>gtk.MESSAGE_ERROR</literal>.</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter role="keyword">buttons</parameter>&nbsp;:</term>
	<listitem><simpara>the predefined set of buttons to use:
<literal>gtk.BUTTONS_NONE</literal>, <literal>gtk.BUTTONS_OK</literal>,
<literal>gtk.BUTTONS_CLOSE</literal>, <literal>gtk.BUTTONS_CANCEL</literal>,
<literal>gtk.BUTTONS_YES_NO</literal>,
<literal>gtk.BUTTONS_OK_CANCEL</literal></simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter
role="keyword">message_format</parameter>&nbsp;:</term>
	<listitem><simpara>a string containing the message text or
None</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a new <link
linkend="class-gtkmessagedialog"><classname>gtk.MessageDialog</classname></link> 
widget</simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>Creates a new <link
linkend="class-gtkmessagedialog"><classname>gtk.MessageDialog</classname></link>, 
which is a simple dialog with an icon indicating the dialog type (error,
warning, etc.) specified by <parameter>type</parameter> and some text
(<parameter>message_format</parameter>) the user may want to see.
<parameter>parent</parameter> if specified indicates the transient parent of
the dialog. The <parameter>flags</parameter> allow the specification special
dialog characteristics: make the dialog modal
(<literal>gtk.DIALOG_MODAL</literal>) and destroy the dialog when the parent is
destroyed (<literal>gtk.DIALOG_DESTROY_WITH_PARENT</literal>). When the user
clicks a button a "response" signal is emitted with response IDs.
<parameter>buttons</parameter> specifies the set of predefined buttons to
use: <literal>gtk.BUTTONS_NONE</literal>, <literal>gtk.BUTTONS_OK</literal>,
<literal>gtk.BUTTONS_CLOSE</literal>, <literal>gtk.BUTTONS_CANCEL</literal>,
<literal>gtk.BUTTONS_YES_NO</literal>,
<literal>gtk.BUTTONS_OK_CANCEL</literal>. See <link
linkend="class-gtkdialog"><classname>gtk.Dialog</classname></link> for more
details.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

  <refsect2 id="method-gtkmessagedialog--set-markup">
    <title>gtk.MessageDialog.set_markup</title>

<programlisting><methodsynopsis language="python">
    <methodname>set_markup</methodname>
    <methodparam><parameter role="keyword">str</parameter></methodparam>
  </methodsynopsis></programlisting>
  <variablelist>
    <varlistentry>
      <term><parameter role="keyword">str</parameter>&nbsp;:</term>
      <listitem><simpara>a markup string (see the <link
      linkend="pango-markup-language">Pango markup language</link>
      reference)</simpara></listitem>
    </varlistentry>
  </variablelist>

      <note>
	<para>This method is available in PyGTK 2.4 and above.</para>
      </note>

      <para>The <methodname>set_markup</methodname>() method sets the text
of the message dialog to the contents of <parameter>str</parameter>. If
<parameter>str</parameter> contains text marked up with Pango markup (see
<xref linkend="pango-markup-language"></xref>), it will be displayed with
those attributes. Note the '&lt;', '&gt;' and '&amp;' characters must be
replaced with '&amp;lt;', '&amp;gt;' and '&amp;amp;' respectively to be
displayed literally.</para>

    </refsect2>

  <refsect2 id="method-gtkmessagedialog--format-secondary-text">
    <title>gtk.MessageDialog.format_secondary_text</title>

<programlisting><methodsynopsis language="python">
    <methodname>format_secondary_text</methodname>
    <methodparam><parameter role="keyword">message_format</parameter></methodparam>
  </methodsynopsis></programlisting>
  <variablelist>
    <varlistentry>
          <term><parameter role="keyword">message_format</parameter>&nbsp;:</term>
          <listitem><simpara>The text to be displayed as the secondary text
or <literal>None</literal></simpara>.</listitem>
    </varlistentry>
  </variablelist>

      <note>
	<para>This method is available in PyGTK 2.6 and above.</para>
      </note>

      <para>The <methodname>format_secondary_text</methodname>() method sets
the secondary text of the message dialog to the text specified by
<parameter>message_format</parameter>. Note that setting a secondary text
makes the primary text bold, unless you have provided explicit
markup.</para>

    </refsect2>

  <refsect2 id="method-gtkmessagedialog--format-secondary-markup">
    <title>gtk.MessageDialog.format_secondary_markup</title>

<programlisting><methodsynopsis language="python">
    <methodname>format_secondary_markup</methodname>
    <methodparam><parameter role="keyword">message_format</parameter></methodparam>
  </methodsynopsis></programlisting>
  <variablelist>
    <varlistentry>
      <term><parameter role="keyword">message_format</parameter>&nbsp;:</term>
      <listitem><simpara>A string containing the pango markup to use as
secondary text.</simpara></listitem>
    </varlistentry>
  </variablelist>

      <note>
	<para>This method is available in PyGTK 2.6 and above.</para>
      </note>

      <para>The <methodname>format_secondary_markup</methodname>() method
sets the secondary text to the markup text specified by
<parameter>message_format</parameter>. Note that setting a secondary text
makes the primary text become bold, unless you have provided explicit
markup.</para>

    </refsect2>

    <refsect2 id="method-gtkmessagedialog--set-image">
      <title>gtk.MessageDialog.set_image</title>

      <programlisting><methodsynopsis language="python">
        <methodname>set_image</methodname>
        <methodparam><parameter role="keyword">image</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">image</parameter>&nbsp;:</term>
          <listitem><simpara>the image widget</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.10 and above.</para>
      </note>

      <para>The <methodname>set_image</methodname>() method sets the
      dialog's image to the <link
      linkend="class-gtkwidget"><classname>gtk.Widget</classname></link>
      specified by <parameter>image</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gtkmessagedialog--get-image">
      <title>gtk.MessageDialog.get_image</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_image</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>the dialog's image.</simpara></listitem>
      </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.14 and above.</para>
      </note>

      <para>
	The <methodname>get_image</methodname>() method gets the dialog's image.
      </para>

    </refsect2>

    <refsect2 id="method-gtkmessagedialog--get-message-area">
      <title>gtk.MessageDialog.get_message_area</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_message_area</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>A <link linkend="class-gtkvbox"><classname>gtk.VBox</classname></link> corresponding to the "message area" in the message_dialog.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.22 and above.</para>
      </note>

      <para>The <methodname>get_message_area</methodname>() method returns the message area of the dialog.
      This is the box where the dialog's primary and secondary labels are packed. You can add your own
      extra content to that box and it will appear below those labels, on the right side of the dialog's
      image (or on the left for right-to-left languages). See
      <link linkend="method-gtkdialog--get-content-area"><methodname>get_content_area</methodname></link>
      for the corresponding function in the parent
      <link linkend="class-gtkdialog"><classname>gtk.Dialog</classname></link>.</para>

    </refsect2>

  </refsect1>

</refentry>
