<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY legal SYSTEM "legal.xml">
<!ENTITY date "Mar. 30, 2002"> <!-- date the manual was last updated -->
<!ENTITY app "<application>Glade</application>">
]>

<article id="index" lang="en">

  <articleinfo> 
  <title>Glade Turbo-Start</title>
    <copyright>
      <year>2000</year>
      <holder>Compaq Computer Corporation</holder>
    </copyright>

    <publisher>
      <publishername>
	GNOME Documentation Project
      </publishername>
    </publisher>

    &legal;

    <legalnotice id="feedback">
      <title>Feedback Information</title>
      <para>
	To report a bug or make a suggestion regarding this
	application or this documentation, please see  the
	<ulink type="help"
	       url="ghelp:gnome-feedback">GNOME Feedback Page</ulink>.
      </para>
    </legalnotice>

    <authorgroup>
      <author>
	  <firstname>Paul</firstname>
	  <surname>Drongowski</surname>
	  <affiliation>
		<orgname>Compaq Computer Corporation</orgname>
	  </affiliation>
	</author>
  </authorgroup>

    <revhistory>

	<revision>
	  <revnumber>1.0</revnumber>
	  <date>20 May 2000</date> <!-- or use &date; -->
	  <revdescription>
                   <para role="author">Paul J. Drongowski
                     <email>paul.drongowski@compaq.com</email></para>
                   <para role="publisher">GNOME Documentation Project</para>
          </revdescription>

	</revision>

  </revhistory>
     <releaseinfo>
       This is the Glade Turbo Start Guide. It was last updated on &date;.
    </releaseinfo>

  </articleinfo>


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

 <!-- ============= Introduction ============================= -->

 <sect1 id="gladeturbostart">
  <title>Glade Turbo-Start</title>
  <para>
   This is just enough info to get started. I would also recommend reading
   the <citetitle>Glade FAQ</citetitle> which comes with the
   distribution and check out the
   <ulink url="http://glade.gnome.org/features.html"
   type="http">screenshots</ulink>.
  </para>

  <!-- ============= Building Glade ========================== -->
  <sect2 id="building-glade">
   <title>Building Glade</title>
   <para>
    If you're a Compaq Alpha Linux user like me, you'll need to build
    <application>Glade</application> for your platform. The
    <filename>README</filename> and <filename>INSTALL</filename> files
    that comes with <application>Glade</application> are pretty
    good. Read them and follow the directions. The <filename
    class="directory">doc</filename> subdirectory also has some
    helpful files, especially <filename>manual.txt</filename>. 
   </para>
   <para>
    There was one problem that occured while building
    <application>Glade</application>  v0.5.7 for RedHat
    Linux 6.1 on Alpha. The build failed while creating the natural language
    support (NLS) stuff in the <filename
    class="directory">po</filename> subdirectory. When NLS was
    disabled, <application>Glade</application> built OK.
   </para>
   <para>
    Look for future Alpha Linux distributions to provide
    <application>Glade</application> pre-built for Alpha.
   </para>
  </sect2>


  <!-- ============= Running Glade ========================== -->
  <sect2 id="running-glade">
    <title>Running Glade</title>
    <para>
     If <application>Glade</application> is on your path (if installed
     into <filename class="directory">/usr/local/bin</filename>, for
     example), then just type <command>glade</command> to start
     running it from the shell. 
    </para>
    <para>
     <application>Glade</application> displays three windows:
     <itemizedlist>
      <listitem>
       <para>
        The main Glade window (file/settings/build)
       </para>
      </listitem>
      <listitem>
       <para>
        The Property Editor
       </para>
      </listitem>
      <listitem>
       <para>
        The Palette
       </para>
      </listitem>  
     </itemizedlist>
    </para>

    <para>
     Use the <interface>Project</interface> window to open an exiting
     project or to create a new one. I would recommend changing some
     settings in the <interface>Project Options</interface> dialog
     which is found under the <guimenu>File</guimenu> menu. For
     example, you'll probably want to change the <guilabel>Project
     Directory</guilabel> and the <guilabel>Project Name</guilabel> on
     the <guilabel>General</guilabel> tabbed page. <guilabel>Program
     Name</guilabel> and <guilabel>Project File</guilabel> will change
     accordingly. The <guilabel>C Options</guilabel> tabbed page
     controls C code generation including the names of certain
     specific generated files: 

     <itemizedlist>
      <listitem>
       <para>
        Interface creation functions &mdash;
        (<filename>interface.c</filename>,
        <filename>interface.h</filename>)
       </para>
      </listitem>
      <listitem>
       <para>
        Signal handler and callback functions &mdash;
        (<filename>callbacks.c</filename>,
        <filename>callbacks.h</filename>)
       </para>
      </listitem>
      <listitem>
       <para>
        Support functions &mdash; (<filename>support.c</filename>,
        <filename>support.h</filename>)
       </para>
      </listitem>  
     </itemizedlist>

     As noted in the <citetitle>Glade FAQ</citetitle>, your signal
     handler functions are in the callbacks source files. You should
     not have to change anything in the interface and support files.
    </para>

    <para>
     Clicking on the <guibutton>Build</guibutton> button or choosing
     <guimenuitem>Build Source Code</guimenuitem> from the
     <guimenu>File</guimenu> menu will ask
     <application>Glade</application> to generate C code.
    </para>
 
  </sect2>

  <!-- ============= The Palette ========================= -->
  <sect2 id="thepalette">
   <title>The Palette</title>
   <para>
    The <interface>Palette</interface> displays the widgets that are
    available for user interface design. They are divided into three
    categories:

     <itemizedlist>
      <listitem>
       <para>
        GTK+ Basic
       </para>
      </listitem>
      <listitem>
       <para>
        GTK+ Additional
       </para>
      </listitem>
      <listitem>
       <para>
        Gnome
       </para>
      </listitem>  
     </itemizedlist>
    </para>

    <para>
     The <guiicon>window</guiicon> icon in the upper left corner is
     the place to start. Click on it to create a new
     window. <application>Glade</application> will draw the new window
     and now you can choose other widgets from the
     <interface>Palette</interface> and add them to the window.
    </para>

    <para>
     <application>Glade</application> uses "boxes" to organize and
     layout widgets. If you intend to add more than one widget to your
     window (and you probably will!), choose and place boxes in the
     window. Your choices are: 

     <itemizedlist>
      <listitem>
       <para>
        Horizontal box
       </para>
      </listitem>
      <listitem>
       <para>
        Vertical box
       </para>
      </listitem>
      <listitem>
       <para>
        Table
       </para>
      </listitem>
      <listitem>
       <para>
        Fixed positions
       </para>
      </listitem>
      <listitem>
       <para>
        Horizontal button box
       </para>
      </listitem>
      <listitem>
       <para>
        Vertical button box
       </para>
      </listitem>

  
     </itemizedlist>
    </para>

    <para>
     Boxes can be nested to create complex layout structures. When
     creating horizontal and vertical boxes, you'll be asked how many
     rows or columns (subdivisions) to create.
    </para>

    <para>
     Once boxes have been put down, you can add specific widgets like
     labels, buttons and other, more complicated widgets into the
     boxes. Notice that <application>Glade</application> "packs"
     widgets into the layout which eliminates a lot of tedious
     work. When you select a widget, the
     <interface>Properties</interface> window will display its current
     properties such as the widget's name. The
     <guilabel>Signals</guilabel> tabbed page within the
     <interface>Property Editor</interface> is the place to attach
     signal handler functions to the widget.
    </para>

    <para>
     The example project that I created has one window divided into
     two parts using the Vertical box layout. The top box contains a
     menu bar and the bottom box is subdivided into (two) left and
     right parts using a Horizontal box layout. The menu bar contains
     a <guimenu>File</guimenu> and <guimenu>Help</guimenu> menu  with
     some menu items beneath each menu. The left part of the
     Horizontal layout contains a scrolled window which, in turn,
     contains a viewport with a tree widget inside. The right part
     contains a Notebook widget with three tabbed pages.
    </para>

   <para>
     The widget tree can be shown choosing <guimenuitem>Show Widget
     Tree</guimenuitem> under the <guimenu>View</guimenu> menu in the
     main <application>Glade</application> window.  The widget tree
     for my example application  has the overall shape: 

     <itemizedlist>
      <listitem>
       <para>
        Window
        <itemizedlist>
         <listitem>
          <para>
           Vertical Box
           <itemizedlist>
            <listitem>
             <para>
              Menu Bar
             </para>
            </listitem>
            <listitem>
             <para>
              Horizontal Box
              <itemizedlist>
               <listitem>
                <para>
                 Scrolled Window
                 <itemizedlist>
                  <listitem>
                   <para>
                    Viewport
                    <itemizedlist>
                     <listitem>
                      <para>
                       Tree
                      </para>
                     </listitem>
                    </itemizedlist> 
                   </para>
                  </listitem>
                 </itemizedlist>
                </para>
               </listitem>
               <listitem>
                <para>
                 Notebook
                </para>
               </listitem>
              </itemizedlist>
             </para>
            </listitem>
           </itemizedlist>
          </para>
         </listitem>
        </itemizedlist>
       </para>
      </listitem>
     </itemizedlist>
   </para>

<!--
    <figure id="glade-tree">
     <title>The Widget Tree</title>
     <screenshot>
      <screeninfo>The Widget Tree</screeninfo>
      <graphic fileref="glade_tree" format="png"
       srccredit="muet">
      </graphic>
     </screenshot>
    </figure>
-->

   <para>
    The <interface>Menu Bar</interface> and
    <interface>Notebook</interface> can be expanded further to view
    individual menus, menu items, pages, etc. The widget tree is good
    way to browse and examine the way that widgets nest.
   </para>
  </sect2>


  <!-- ============= Menu Editor ========================= -->
  <sect2 id="menueditor">
   <title>Menu Editor</title>
   <para>
    After placing a <interface>Menu Bar</interface> widget, use the
    left button to select the widget. Click the right button on the
    <interface>Menu Bar</interface> to get a pop-up menu of
    commands. Choose the <guimenuitem>Edit Menu</guimenuitem> item and
    <application>Glade</application> will display the <interface>Menu
    Editor</interface>. This is where you can create the menu
    structure for your application.
   </para>

   <para>
    Click the <guibutton>Add</guibutton> button to add a new menu or
    menu item. Change the <guilabel>Label</guilabel> and
    <guilabel>Name</guilabel> field as
    desired. <guilabel>Label</guilabel> is the text label that will
    appear in the menu or menu bar. Name will be used to build a
    signal handler. The <guilabel>Handler</guilabel> field will update
    as new <guilabel>Name</guilabel> information is entered. The
    handler name will begin with "on_" and end with "_activate" as in: 
    <function>on_open_project_activate</function>.  Use the left and
    right arrows to create levels of menu items. Indentation denotes
    menu substructure.
   </para>

   <para>
    Click the <guilabel>Apply</guilabel> button to make the current
    menu information appear in the <interface>edit
    window</interface>. You can play with the menu items to try them
    out.
   </para>
  </sect2>


  <!-- ============= Generating Code ========================= -->
  <sect2 id="generatingcode">
   <title>Generating Code</title>
   <para>
    After the window looks the way you want it, click on the
    <guibutton>Build</guibutton> button to generate
    code. <application>Glade</application> also generates information
    for <application>autoconf</application> making it easy to build
    the application on your platform. The following files and
    directories are created for a simple project: 

     <itemizedlist>
      <listitem>
       <para>
        <filename>AUTHORS</filename> &mdash; Empty, needed for GNU compliance
       </para>
      </listitem>
      <listitem>
       <para>
        <filename>NEWS</filename> &mdash; Empty, needed for GNU compliance
       </para>
      </listitem>
      <listitem>
       <para>
        <filename>README</filename> &mdash; Empty, needed for GNU compliance
       </para>
      </listitem>  
      <listitem>
       <para>
        <filename>Makefile.am</filename> &mdash; Use
        <application>automake</application> with this file to produce
        <filename>Makefile.in</filename> 
       </para>
      </listitem>
      <listitem>
       <para>
        <filename>acconfig.h</filename> &mdash;
        <application>Autoconf</application> information
       </para>
      </listitem>
      <listitem>
       <para>
        <filename>autogen.sh</filename> &mdash; Run this to build the
        application 
       </para>
      </listitem>  
      <listitem>
       <para>
        <filename>configure.in</filename> &mdash; Needed by
        <application>autoconf</application> to produce a configure
        script
       </para>
      </listitem>
      <listitem>
       <para>
        <filename class="directory">macros/</filename> &mdash; Build
        related macros (m4)
       </para>
      </listitem>
      <listitem>
       <para>
        <filename>pm.glade</filename> &mdash; The
        <application>Glade</application> project file for the application
       </para>
      </listitem>  
      <listitem>
       <para>
        <filename class="directory">po/</filename> &mdash;
        Localization (NLS) support files
       </para>
      </listitem>
      <listitem>
       <para>
        <filename class="directory">src/</filename> &mdash;
        Application source files
       </para>
      </listitem>
      <listitem>
       <para>
        <filename>stamp-h.h</filename> &mdash; Timestamp
       </para>
      </listitem>  
     </itemizedlist>

    The <filename class="directory">src</filename> subdirectory
    contains the source files for the application. Six of these files
    were mentioned earlier:

     <itemizedlist>
      <listitem>
       <para>
        Interface creation functions &mdash;
        (<filename>interface.c</filename>,
        <filename>interface.h</filename>)
       </para>
      </listitem>
      <listitem>
       <para>
        Signal handler and callback functions &mdash;
        (<filename>callbacks.c</filename>,
        <filename>callbacks.h</filename>)
       </para>
      </listitem>
      <listitem>
       <para>
        Support functions &mdash; (<filename>support.c</filename>,
        <filename>support.h</filename>)
       </para>
      </listitem>  
     </itemizedlist>

    <application>Glade</application> also generates
    <filename>main.c</filename>. <application>Glade</application> does
    *not* overwrite the following files:

     <itemizedlist>
      <listitem>
       <para>
        <filename>main.c</filename>
       </para>
      </listitem>
      <listitem>
       <para>
        <filename>callbacks.h</filename>
       </para>
      </listitem>
      <listitem>
       <para>
        <filename>callbacks.c</filename>
       </para>
      </listitem>  
     </itemizedlist>

    Feel free to edit these files. <filename>callbacks.c</filename>
    contain the stubbed signal handling functions which respond to
    user actions. This is where you need to hook in your application code.
    </para>

    <para>
     To prepare to build the application, just enter
     <command>autogen.sh</command> at the shell
     prompt. <application>Autoconf</application>  will create
     configuration information and makefiles will be generated. Now
     just enter <command>make</command> to actually build the
     application. <application>Make</application> will recursively
     work its way through the build process leaving the final
     executable program in the <filename
     class="directory">src</filename> subdirectory. Run the program
     and check out your interface!
   </para>
  </sect2>


  <!-- =========== Building Confidence  ======================= -->
  <sect2 id="buildingconfidence">
   <title>Building Confidence</title>
   <para>
    Here are some things to try in order to build confidence with
    <application>Glade</application>.
   </para>

   <para>
    Edit <filename>callbacks.c</filename> and add
    <function>printf</function>'s to the signal handler
    functions. Remake the application, run it, and watch the messages
    appear as the signal handling functions are invoked in response to
    widget actions.
   </para>
  
   <para>
    Your application window may have been too small as displayed the
    first time around. (Mine certainly was.) Open the
    <application>Glade</application> project and click the icon for
    the window widget in the main <application>Glade</application>
    window. Go to the <guilabel>Widget</guilabel> tabbed page in the
    <interface>Property Editor</interface>. Change the
    <guilabel>Default Width</guilabel> and <guilabel>Height</guilabel>
    fields to adjust the size of the application window. Generate C
    source code again and make the application. Run the application
    again and congratulate yourself on a job well done! 
   </para>
  </sect2>


  <!-- =========== What's Next?  ======================= -->
  <sect2 id="whatsnext">
   <title>What's Next?</title>
   <para>
    It should be possible to get to this point without knowing a lick
    of GTK+. The next step is to learn more about GTK (especially the
    more complicated widgets like trees) and start filling out the
    stubs.
   </para>
  </sect2>


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

  <sect2 id="authors">
   <title>Authors</title>
   <para>
    <application>Glade</application> was written by Damon Chaplin
    (<email>damon@gnome.org</email>).  This guide was written by
    Paul J. Drongowski (<email>paul.drongowski@compaq.com</email>).
    Conversion to DocBook was done by Dan Mueth
    (<email>d-mueth@uchicago.edu</email>).
   </para>

<!--
   <para>
    <application>Glade</application> was written by Damon Chaplin
    (<email>damon@gnome.org</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>. If you are using
    GNOME 1.1 or later, 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 guide was written by Paul J. Drongowski
    (<email>paul.drongowski@compaq.com</email>). Please send all comments and
    suggestions regarding this manual to the <ulink type="http"
    url="http://www.gnome.org/gdp">GNOME Documentation Project</ulink> 
    by sending an email to <email>docs@gnome.org</email> or to the
    author of this document directly. You can also
    submit comments online by using the <ulink type="http"
    url="http://www.gnome.org/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>

   -->

  </sect2>


  <!-- ============= Application License ============================= -->
<!--
  <sect2 id="license">
   <title>License</title>
   <para>
    This program is free software; you can redistribute it and/or
    modify it under the terms of the <citetitle>GNU General Public
    License</citetitle> 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>
  </sect2>
-->


 </sect1>

</article>



