pygtk-docs r797 - in trunk/2.0: . examples tut

[esr svn gnome org]

Author: esr
Date: Tue Oct 21 09:49:28 2008
New Revision: 797
URL: http://svn.gnome.org/viewvc/pygtk-docs?rev=797&view=rev

Log:
Add documentation and example for MessageDialog widget.


Added:
   trunk/2.0/examples/message.py
Modified:
   trunk/2.0/ChangeLog
   trunk/2.0/tut/MiscellaneousWidgets.xml
   trunk/2.0/tut/UndocumentedWidgets.xml

Added: trunk/2.0/examples/message.py
==============================================================================
--- (empty file)
+++ trunk/2.0/examples/message.py	Tue Oct 21 09:49:28 2008
@@ -0,0 +1,12 @@
+#!/usr/bin/env python
+
+# message.py -- example program illustrating use of message dialog widget 
+
+import pygtk
+pygtk.require('2.0')
+import gtk
+
+if __name__ == "__main__":
+    message = gtk.MessageDialog(type=gtk.MESSAGE_ERROR, buttons=gtk.BUTTONS_OK)
+    message.set_markup("An example error popup.")
+    message.run()

Modified: trunk/2.0/tut/MiscellaneousWidgets.xml
==============================================================================
--- trunk/2.0/tut/MiscellaneousWidgets.xml	(original)
+++ trunk/2.0/tut/MiscellaneousWidgets.xml	Tue Oct 21 09:49:28 2008
@@ -808,6 +808,68 @@
 application, then you can simply pack another layout widget into the boxes
 provided. For example, you could pack a table into the vertical box.</para>
 
+      <sect2 id="sec-MessageDialogs">
+        <title>Message Dialogs</title>
+
+<para>A message dialog is a specialization of the already rather simple *Dialog*
+widget for displaying standardized error, question, and information
+popups.  Invoke it like this:</para>
+
+      <programlisting>
+message = gtk.MessageDialog(parent=None, 
+                            flags=0, 
+                            type=gtk.MESSAGE_INFO, 
+                            buttons=gtk.BUTTONS_NONE, 
+                            message_format=None)
+</programlisting>
+
+<para>The <parameter>type</parameter> flag selects a stock icon to be 
+displayed in the message:</para>
+
+      <programlisting>
+MESSAGE_INFO - information message
+MESSAGE_WARNING - warning (or recoverable error) message
+MESSAGE_QUESTION - question that can be answered with a button click
+MESSAGE_ERROR - error message
+</programlisting>
+
+<para>To set the text for the message, feed it a Pango markup string.  As
+a matter of style, you probably want to stick to relatively terse,
+one-sentence messages when using this widget.</para>
+
+      <programlisting>
+message.set_markup("Sample message, could contain pango markup")
+</programlisting>
+
+<para>Here's an example program, <ulink
+url="examples/message.py"><command>message.py</command></ulink></para>
+
+      <programlisting>
+     1	#!/usr/bin/env python
+       
+     2	# message.py -- example program illustrating use of message dialog widget 
+       
+     3	import pygtk
+     4	pygtk.require('2.0')
+     5	import gtk
+       
+     6	if __name__ == "__main__":
+     7	    message = gtk.MessageDialog(type=gtk.MESSAGE_ERROR, buttons=gtk.BUTTONS_OK)
+     8	    message.set_markup("An example error popup.")
+     9	    message.run()
+</programlisting>
+
+<para>We used <method>run()</method> here to make the dialog modal; we
+could have achieved the same result by setting
+<parameter>flags</parameter> to <constant>DIALOG_MODAL</constant>. and
+doing this instead:</para>
+
+      <programlisting>
+    message.show()
+    gtk.main()
+</programlisting>
+
+      </sect2>
     </sect1>
 
 <!-- ===================================================================== -->

Modified: trunk/2.0/tut/UndocumentedWidgets.xml
==============================================================================
--- trunk/2.0/tut/UndocumentedWidgets.xml	(original)
+++ trunk/2.0/tut/UndocumentedWidgets.xml	Tue Oct 21 09:49:28 2008
@@ -71,13 +71,6 @@
     </sect1>
 
 <!-- ===================================================================== -->
-    <sect1 id="sec-MessageDialog">
-      <title>Message Dialog</title>
-      <para></para>
-
-    </sect1>
-
-<!-- ===================================================================== -->
     <sect1 id="sec-GammaCurve">
       <title>Gamma Curve</title>
       <para></para>