<!DOCTYPE article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
        <!-- if not using PNG graphic, replace reference above with
             .....PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[
         -->
<!ENTITY version "0.6gnome1"> <!-- replace with application version -->
]>


<!-- 
      (Do not remove this comment block.)
  Maintained by the GNOME Documentation Project
  http://developer.gnome.org/projects/gdp
  Template version: 1.0.3
  Template last modified: Nov 16, 2000
-->


<!-- =============Document Header ============================= -->

<article id="index"> <!-- please do not change the id -->

  <artheader>
    <title>gdialog Manual</title>
    <copyright>
      <year>2001</year>
      <holder>Patanjali Somayaji</holder>
    </copyright>

  <!-- translators: uncomment this:

  <copyright>
   <year>2000</year>
   <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
  </copyright>

   -->

  <!-- do not put authorname in the header except in copyright - use
  section "authors" below -->

  <!-- Use this legal notice for online documents which depend on -->
  <!-- core GNOME packages.                                       -->
  <legalnotice id="legalnotice">
   <para>
    Permission is granted to copy, distribute and/or modify this document
    under the terms of the <ulink type="help" 
    url="gnome-help:fdl"><citetitle>GNU Free Documentation
    License</citetitle></ulink>, Version 1.1 or any later version 
    published by the Free Software Foundation with no Invariant Sections, 
    no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
    can be found <ulink type="help" url="gnome-help:fdl">here</ulink>.
   </para>
   <para>
    Many of the names used by companies to distinguish their products and
    services are claimed as trademarks. Where those names appear in any
    GNOME documentation, and those trademarks are made aware to the members
    of the GNOME Documentation Project, the names have been printed in caps
    or initial caps.
   </para>
  </legalnotice>

  <!-- This is the manual version, not application version. --> 
    <releaseinfo>
       This is version 0.1 of the GDialog manual.
    </releaseinfo>

  </artheader>

 <!-- ============= Document Body ============================= -->

 <!-- ============= Introduction ============================== -->
  <sect1 id="intro">
    <title>Introduction</title>

    <para>
     <application>gdialog</application> is a command prompt 
     application which displays GNOME dialog boxes. It is meant to be 
     used as a quick way to display dialog boxes within shell scripts. 
     
    </para>
    <para>
     <application>gdialog</application> helps you to 
     create small and useful commonly used dialog boxes, like 
     message boxes, information boxes, input boxes, etc.  
    </para>

    <para>
      <application>gdialog</application> is included in the
      <filename>gnome-utils</filename> package, which is part of the
      GNOME desktop environment. This document describes version
      &version; of <application>gdialog</application>.
    </para>
  </sect1>


 <!-- ================ Usage ================================ -->

  <sect1 id="usage">
    <title>Using gdialog</title>

    <!-- ========= Basic Usage =========================== -->
    <sect2 id="mainwin">
      <title>Basic usage</title>

    <para>	  
	<application>gdialog</application> is a utility 
	meant for use in shell scripts or from the command prompt.
	Hence, to run gdialog, the complete description needs to
	be given on the command line or in the shell 
	script about the type of dialog box 
	to be created and shown to the user. For example, type the 
	following in a GNOME terminal, or put it in a shell script -
	<command>
	gdialog --msgbox "Here's a test message !" 200 150 
	</command>
	creates and displays the dialog box shown in 
	<xref linkend="example-dialog">.

        <!-- ==== Figure ==== -->
        <figure id="example-dialog">
	  <title>gdialog example</title>
	  <screenshot>
	    <screeninfo>gdialog msgbox example</screeninfo>
	    <graphic fileref="figures/example-dialog" format="png" 
			srccredit="Patanjali Somayaji">
            </graphic>
	  </screenshot>
	</figure>
    <!-- ==== End of Figure ==== -->
      </para> 

	<para>
	The complete command line options list for 
	<application>gdialog</application> is</para>
	<para> 
	<command>
	gdialog [--title &lt;title&gt;] [--separate-output] 
	[--backtitle &gt;backtitle&gt;] [--clear] &lt;Box options&gt;
	</command>
	</para>
	<para>	
	<command>title</command> is used to give a title to the dialog. 
	</para>
	<para>
	"Box Options" can be one of the following 
	<itemizedlist>
	<listitem>
	    <para>
	<command>
		[--defaultno] --yesno 
		&lt;text&gt; &lt;height&gt; &lt;width&gt; 
	</command>
	    </para>
	</listitem>
	<listitem>
	    <para>
	<command>
		--msgbox
		&lt;text&gt; &lt;height&gt; &lt;width&gt; 
	</command>
	    </para>
	</listitem>
	<listitem>
	    <para>
	<command>
		 --infobox   
		&lt;text&gt; &lt;height&gt; &lt;width&gt; 
	</command>
	    </para>
	</listitem>
	<listitem>
	    <para>
	<command>
		--inputbox  
		&lt;text&gt; &lt;height&gt; &lt;width&gt;
		[&lt;init&gt;] 
	</command>
	    </para>
	</listitem>
	<listitem>
	    <para>
	<command>
		 --textbox   &lt;file&gt; 
		&lt;height&gt; &lt;width&gt; 
	</command>
	    </para>
	</listitem>
	<listitem>
	    <para>
	<command>
		 --menu   
		&lt;text&gt; &lt;height&gt; &lt;width&gt; 
		&lt;menu height&gt; &lt;tag1&gt; &lt;item1&gt; ...
	</command>
	    </para>
	</listitem>
	<listitem>
	    <para>
	<command>
		 --checklist  
		&lt;text&gt; &lt;height&gt; &lt;width&gt;
		&lt;list height&gt; &lt;tag1&gt; &lt;item1&gt; &lt;status1&gt; ...
	</command>
	    </para>
	</listitem>
	<listitem>
	    <para>
	<command>
		 --radiolist    
		&lt;text&gt; &lt;height&gt; &lt;width&gt;
		&lt;list height&gt; &lt;tag1&gt; &lt;item1&gt; &lt;status1&gt; ...
	</command>
	    </para>
	</listitem>
	<listitem>
	    <para>
	<command>

		--gauge  
		&lt;text&gt; &lt;height&gt; &lt;width&gt;
		&lt;percent&gt;
	</command>
	    </para>
	</listitem>
	<listitem>
	    <para>
	<command>
		 --guage   &lt;file&gt; 
		&lt;text&gt; &lt;height&gt; &lt;width&gt;
		&lt;percent&gt;
	</command>
	    </para>
	</listitem>
	
	</itemizedlist>
      </para>
	<para>	Using gdialog to show different types of dialog shown above 
	is explained 
	in the following sections. 
	</para>

    </sect2>
 
    <!-- ========================================================= 
      Additional Sect2's should describe additional windows, such as
      larger dialog boxes, or functionality that differs significantly
      from the most immediate functions of the application. Make the
      structure logical.
      =============================================================  -->
  </sect1>

<sect1 id="dialogs">
<title>Using different tyes of dialog boxes</title>
	
	<para>
	This section shows you how to create and display different 
	types of dialogs. For all the examples, we'll be using a 
	width of 250 and a height of 150 in place of  
	<command>&lt;width&gt;</command> and 
	<command>&lt;height&gt;</command> for the width and height
	of the dialog box to be displayed. 
	</para>
	

	<sect2 id="yesnobox">
	<title>Creating a Confirmation Dialog</title>
	<para>
	You can create a dialog box that shows a question and a "Yes" and 
	a "No" button using the <command>--yesno</command> option. 
	For example, to create a dialog box with the 
	title as "My Dialog",
	and question to be shown "Should I exit ?"
	use the following command 
	<command>
	gdialog --title "My Dialog" 
		--yesno
		"Should I exit ?"
		250 150		 
	</command>
	</para>
	<para>
	The above command displays the dialog box shown in figure
	<xref linkend="gdialog-yesno">. 
      	
        <figure id="gdialog-yesno">
	  <title>confirmation box example</title>
	  <screenshot>
	    <screeninfo>gdialog confirmation box example</screeninfo>
	    <graphic fileref="figures/gdialog-yesno" format="png" 
			srccredit="Patanjali Somayaji">
            </graphic>
	  </screenshot>
	</figure>
	 
	</para>		
	<para>
	The return value from gdialog is 0 if the user clicked on "Yes"
	and 1 if the user clicked on "No". By default, the "Yes" button is
	highlighted when the dialog is displayed. In case you want the "No" 
	button to be highlighted, add <command>--defaultno</command>
	</para>	
	</sect2>
	
	<sect2 id="messagebox">
	<title>Creating a Message Box</title>
	<para>
	You can create a dialog box that shows a message 
	using the <command>--msgbox</command> option. 
	For example, to create a dialog box with the 
	title as "My Dialog",
	and message to be shown "Here's a message !"
	use the following command 
	<command>
	gdialog --title "My Dialog" 
		--msgbox
		"Here's a message"
		250 150		 
	</command>
	</para>
	<para>
	The above command displays the dialog box shown in figure
	<xref linkend="gdialog-msgbox">. 
      	
        <figure id="gdialog-msgbox">
	  <title>Message box example</title>
	  <screenshot>
	    <screeninfo>gdialog message box example</screeninfo>
	    <graphic fileref="figures/gdialog-msgbox" format="png" 
			srccredit="Patanjali Somayaji">
            </graphic>
	  </screenshot>
	</figure>
	 
	</para>		
	</sect2>

</sect1>



 <!-- ============= Various Sections ============================= -->

 <!-- Here you should add, if necessary, several more sect1's,
 describing other windows (besides the main one), file formats,
 preferences dialogs,  etc. as appropriate. Try not to make any of
 these sections too long. -->


 <!-- ============= Bugs ================================== -->
 <!-- This section should describe known bugs and limitations of
      the program if there are any - please be frank and list all
      problems you know of. -->
 <sect1 id="bugs">
  <title>Known Bugs and Limitations</title>
  <para>
   This application has no known bugs.
  </para>
 </sect1>


<!-- ============= Authors ================================ -->

 <sect1 id="authors">
  <title>Authors</title>
  <para>
   <application>gdialog</application> was written by Savio Lam
   (<email>lam836@cs.cuhk.hk</email>) and Stuart Herbert
   (<email>S.Herbert@shef.ac.uk</email>). 
   Please send all comments, suggestions, and bug
   reports to the <ulink url="http://bugs.gnome.org" type="http">GNOME
   bug tracking database</ulink>.  (Instructions for submitting bug
   reports can be found <ulink
   url="http://bugs.gnome.org/Reporting.html" type="http">
   on-line</ulink>.)  You can also use <application>Bug Report
   Tool</application> (<command>bug-buddy</command>), available in the
   <guisubmenu>Utilities</guisubmenu> submenu of <guimenu>Main
   Menu</guimenu>, for submitting bug reports.
  </para>

  <para>
   This manual was written by Patanjali Somayaji
   (<email>patanjali@morelinux.com</email>). Please send all comments and
   suggestions regarding this manual to the <ulink type="http"
   url="http://developer.gnome.org/projects/gdp">GNOME Documentation
   Project</ulink> by sending an email to
   <email>docs@gnome.org</email>. You can also add your comments
   online by using the <ulink type="http"
   url="http://developer.gnome.org/projects/gdp/doctable/">GNOME
   Documentation Status Table</ulink>.
  </para>

  <!-- For translations: uncomment this:

  <para>
   Latin translation was done by ME
   (<email>MYNAME@MYADDRESS</email>). Please send all  comments  and
   suggestions regarding this translation to SOMEWHERE.
  </para>

  -->

 </sect1>


 <!-- ============= Application License ============================= -->

 <sect1 id="license">
  <title>License</title>
  <para>
   This program is free software; you can redistribute it and/or
   modify it under the terms of the  <ulink type="help" url="gnome-help:gpl">
    <citetitle>GNU General Public License</citetitle></ulink> as
   published by the Free Software Foundation; 
   either version 2 of the License, or (at your option) any later
   version.
  </para>
  <para>
   This program is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   <citetitle>GNU General Public License</citetitle> for more details.
  </para>
  <para>
   A copy of the <citetitle>GNU General Public License</citetitle> is
   included as an appendix to the <citetitle>GNOME Users
   Guide</citetitle>.  You may also obtain a copy of the
   <citetitle>GNU General Public License</citetitle> from the Free
   Software Foundation by visiting <ulink type="http"
   url="http://www.fsf.org">their Web site</ulink> or by writing to
   <address>
    Free Software Foundation, Inc.
    <street>59 Temple Place</street> - Suite 330
    <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
    <country>USA</country>
   </address>
  </para>
 </sect1>
</article>









