Glade::PerlGenerate - Generate Perl source from a Glade XML project file.

The simplest way to run Glade::PerlGenerate is to use the supplied script 'glade2perl' that is also called by Glade when you hit the 'Build' button.

 glade2perl Project.glade 2

Otherwise you can control every aspect of the source generation by calling the same methods that glade2perl calls:

 use Glade::PerlGenerate;

 Glade::PerlGenerate->Form_from_Glade_File(

   'author'        => 'Dermot Musgrove <dermot.musgrove@virgin.net>',
   'description'   => "This is an example of the Glade-Perl
source code generator",
   'verbose'       => 2,
   'indent'        => '    ',
   'tabwidth'      => 4,
   'diag_wrap'     => 0,
   'write_source'  => 'True',
   'dont_show_UI'  => 'True',
   'autoflush'     => 'True',
   'use_modules'   => 'Example::BusForm_mySUBS',
   'log_file'      => 'Test.log',
   'glade_filename'=> "Example/BusForm.glade"

 );

OR if you want to generate the UI directly from an XML string

 Glade::PerlGenerate->Form_from_XML(

   'xml'           => $xml_string,
   'use_modules'   => ['Example::Project_mySUBS']

 );

Glade::PerlGenerate reads a <GTK-Interface> definition from a Glade file (or a string) using XML::Parser, converts it into a hash of hashes and works its way through this to show the UI using Gtk-Perl bindings. The module can also optionally generate Perl source code to show the UI and handle the signals. Any signal handlers that are specified in the project file but not visible at Generate time will be hijacked to show a 'missing_handler' message_box and a stub for it will be defined in the the UI class for dynamic AUTOLOAD()ing.

The stub will simply show a message_box to prove that the handler has been called and you can write your own with the same name in another module. You then quote this module to the next Generate run and Glade::PerlGenerate will use these handlers and not define stubs.

These options can be specified to the Glade::PerlGenerate->Form_from_Glade_File() and Glade::PerlGenerate->Form_from_XML() methods or with the same name in the options XML files.

Boolean values can be specified as CWTrue|true|Yes|yes|1 or False|false|No|no|0|''|undef

<name>

Name to use for the generated packages. Any spaces, dots or minuses will be removed from the name as these are not valid in perl package names.

<author>

The author's name to appear in generated sources. Backslash-escape any @ signs so that they are passed through perl strings correctly. The default is synthesised from some of the values returned by Perl's gethostbyname localhost e.g. CWDermot Musgrove <dermot.musgrove@virgin.net

<version> - default is 0.01

Version number to use in generated sources. e.g. CW0.53-pre1

<date> - defaults to build time.

The date string to show in sources. e.g. CWChristmas eve 2001

<copying> - default is '# Unspecified copying policy, please contact the author\n# '

Copying text to include in generated sources. Make sure that they are specified as perl # comments so that the generated source is valid.

<description> - default is 'No description'

A general description of the app to appear in sources and about_boxes e.g CWThis is a reference form that contains all the widgets that Glade knows about

<logo> - default 'Logo.xpm'

Use the specified logo in about boxes or if any pixmap is missing

<use_modules> - default means don't use() any other modules

When specified as an arg this is an anonymous array of module names to be use()d in the generated classes. In an options file, a newline separated list of modules to be use()d by generated classes e.g CW['Existing::mySUBS', 'Some::Other::Module']

<allow_gnome> - Default is read from the Glade project file

Bool - whether or not to allow Gnome widgets in the generated source

<file>

Name of Glade file to read

<encoding> - default 'ISO-8859-1'

Character encoding of Glade file eg CWISO-8859-1

<version>

Version of Glade::PerlGenerate that wrote this file.

<logo> - default 'glade2perl_logo.xpm'

Name of the Glade::PerlGenerate logo pixmap used.

<my_perl_gtk> - Default is to use Gtk-Perl's version number

Version number of my Gtk-Perl module. This overrides the number reported by Gtk::Perl so that CVS fixes can be used. CW0.6123 I have CPAN version 0.6123 CW19991001 I have the gnome.org CVS version of 'gnome-perl' that I downloaded on Oct 1st 1999

<my_gnome_libs> - Default is to use gnome-libs version no

Version number of my gnome-libs. This overrides the number reported by `gnome-libs-config --version` so that CVS fixes can be used. CW1.0.58 I have the released version 1.0.58 of 'gnome-libs' CW19991001 I have the gnome.org CVS version of 'gnome-libs' that I downloaded on Oct 1st 1999

<dont_show_UI> - default is to show the UI and wait for user action

Bool - whether to show the UI during the Build. glade2perl sets this to 0 so that the UI is not shown.

<start_time>

Time that this run started

<xml> options that describe the options files

<set_by> - default 'DEFAULT'

Who set the options last.

<site> - Default is /etc/glade2perl.xml

File name containing options for all projects on this site. This option is only meaningful when set by Glade::PerlGenerate->options() or Form_from_File() although it is logged in the project_options file

<user> - Default is ~/.glade2perl.xml

File name containing options for all projects in this user. This option is only meaningful when set by Glade::PerlGenerate->options() or Form_from_File() although it is logged in the project_options file

<project> - Default means don't read or save a file

Filename of project options to read and save. This option is only meaningful when set by Glade::PerlGenerate->options() or Form_from_File() although it is logged in the project_options file

<encoding> - default is <glade><encoding> option

Character encoding of glade2perl.xml options files. This option is only meaningful when set by Glade::PerlGenerate->options() or Form_from_File() although it is saved in the file itself. eg CWISO-8859-1

<indent> - default is 4 spaces

Indent to use for 'nested' source code

 e.g. '  ' (2 spaces)

<tabwidth> - default is 8

Number of spaces to replace with a tab in generated source code e.g. CW4

<write> - default is no source

Where to write the source code. glade2perl sets this to 1. CWSTDOUT Write sources to STDOUT but there will be nothing to run later CWFile.pm Write sources to File.pm They will not run from here and you must cut-paste them CWTrue - write the sources to standard files. CWundef Don't write source code

<hierarchy> - default means don't generate any hierarchy

CW...widget... generates a widget hierarchy eg CW$form->{'__WH'}{'vbox2'}{'table1'}... CW...class... generates a class hierarchy eg CW$form->{'__CH'}{'GtkVBox'}{'vbox2'}{'GtkTable'}{'table1'}... CW...both... both widget and class hierarchies generated CW...ordered... generates an ordered hierarchy that reflects the order that child widgets were added to the UI eg CW$form->{'__WH'}{'vbox2'}{'table1'}{'__C'}[2]... e.g. CWwidget_hierarchy

<style> - default AUTOLOAD

CWAUTOLOAD - OO class implements missing signal handlers with an AUTOLOAD sub CWLibglade - generate libglade code and signal handlers CWsplit - generates each class in its own .pm file. Which language do we want the source to be documented in? e.g. CWpt_BR

<verbose> - default is 2

Level of verbosity of diagnostics

 0  - Quiet/no diagnostics (glade2perl uses this)
 1  - Main project messages and errors only
 2  - also warnings
 4  - also project options and more diagnostics
 6  - also source code as it is generated
 8  - also lookups and conversions
 10 - everything (more than you want?)

<wrap_at> - default is 0 (no breaks)

Maximum diagnostics message line length (approximate)

 0   - no breaks (not easy to read on 80 column displays).
 80  - should display comfortably on 80 column display
 132 - Wrap diagnostics so that lines are about 132 characters long

<autoflush> - default is False (write at end of block)

Bool - whether to autoflush the file output. This is really to force errors to be shown by my editor's shellout in the case of a failure.

<indent> - default is 4 spaces

Indent to use for diagnostic messages and wrapped lines

 e.g. '  ' (2 spaces)

<benchmark> - default means don't add time to the diagnostic messages

Bool - True will cause the time to prefix all diagnostics messages

<log> - Default is to use STDOUT

Write diagnostics and errors to filename if verbose > 0 glade2perl can set this to /path/to/glade/file.glade2perl.log e.g. CW/home/dermot/Devel/Test/Project1.glade2perl.log Which language do we want the diagnostic messages in? e.g. CWde

 <?xml version="1.0" encoding="ISO-8859-1"?>
 <glade2perl-Options>
   <app>
     <allow_gnome>1</allow_gnome>
     <date>Tue Apr 10 05:04:00 BST 2001</date>
     <description>No description</description>
     <logo>Logo.xpm</logo>
     <name>Reference</name>
     <use_modules>Reference_mySUBS</use_modules>
     <version>0.58</version>
   </app>

   <diag>
     <log>/home/dermot/Devel/Glade-Perl/Example/Reference/Project.glade2perl.log</log>
   </diag>

   <glade>
     <directory>/home/dermot/Devel/Glade-Perl/Example/Reference</directory>
     <file>/home/dermot/Devel/Glade-Perl/Example/Reference/Project.glade</file>
     <name_from>Specified as arg to Glade::PerlGenerate-&gt;Form_from_Glade_File</name_from>
     <pixmaps_directory>/home/dermot/Devel/Glade-Perl/Example/Reference/pixmaps</pixmaps_directory>
     <start_directory>/home/dermot/Devel/Glade-Perl/Example/Reference</start_directory>
   </glade>

   <glade2perl>
     <date>Thu Apr 26 13:32:49 BST 2001</date>
     <dont_show_UI>1</dont_show_UI>
     <logo>/home/dermot/Devel/Glade-Perl/Example/Reference/pixmaps/glade2perl_logo.xpm</logo>
     <my_gnome_libs>1.2.13</my_gnome_libs>
     <my_gtk_perl>20010601</my_gtk_perl>
     <package>Glade::PerlProject</package>
     <start_time>Tue Jun 12 11:59:49 BST 2001</start_time>
     <version>0.58</version>
     <xml>
       <params>Params supplied</params>
       <project>/home/dermot/Devel/Glade-Perl/Example/Reference/Project.glade2perl.xml</project>
       <set_by>Glade::PerlGenerate-&gt;use_Glade_Project</set_by>
     </xml>

   </glade2perl>

   <source>
     <style>sxplit</style>
   </source>

   <test>
     <directory>/home/dermot/Devel/Glade-Perl/Example/Reference</directory>
     <first_form>ReferenceForm</first_form>
     <name>Reference</name>
     <use_module>src::Reference</use_module>
   </test>

   <type>glade2perl</type>
 </glade2perl-Options>

 <?xml version="1.0" encoding="ISO-8859-1"?>
 <glade2perl-Options>
   <app>
    <author>Dermot Musgrove &lt;dermot.musgrove@virgin.net&gt;</author>
   </app>

   <diag>
     <LANG>en</LANG>
     <indent>  </indent>
     <verbose>2</verbose>
   </diag>

   <glade2perl>
     <author>Dermot Musgrove &lt;dermot.musgrove@virgin.net&gt;</author>
     <logo>/home/dermot/Devel/HTML-Site/pixmaps/glade2perl_logo.xpm</logo>
     <mru>/home/dermot/Devel/Glade-Perl/Example/Reference/Project.glade</mru>
     <name>Glade::PerlGenerate</name>
     <start_time>Tue Jun 12 11:59:49 BST 2001</start_time>
     <xml>
       <app_defaults>Application defaults</app_defaults>
       <base_defaults>Glade::PerlRun defaults</base_defaults>
       <encoding>ISO-8859-1</encoding>
       <params>DEFAULT</params>
       <site>/etc/glade2perl.xml</site>
       <user>/home/dermot/.glade2perl.xml</user>
     </xml>

   </glade2perl>

   <source>
     <LANG>en</LANG>
     <indent>  </indent>
     <tabwidth>4</tabwidth>
     <write>1</write>
   </source>

 </glade2perl-Options>

 <?xml version="1.0" encoding="ISO-8859-1"?>
 <G2P-Options>
   <app>
     <copying># This library is released under the same conditions as Perl, that
 # is, either of the following:
 #
 # a) the GNU General Public License as published by the Free
 # Software Foundation; either version 1, or (at your option) any
 # later version.
 #
 # b) the Artistic License.
 #
 # If you use this library in a commercial enterprise, you are invited,
 # but not required, to pay what you feel is a reasonable fee to cpan.org
 # at http://www.perl.org or contact donors@perlmongers.org for details.
 # </copying>
   </app>
   <glade2perl>
     <my_gtk_perl>0.7007</my_gtk_perl>
   </glade2perl>
 </G2P-Options>

The module will report several errors or warnings that warn of problems with the Glade file or other unexpected occurences. These are to help me cater for new widgets or widget properties and not because Glade creates inconsistent project files but they do point out errors in hand-edited XML.

projectUI.pm

A perl class/module (projectUI.pm) that contains a class for each toplevel window/dialog, each with a standard method (new) that will construct the UI.

projectSIGS.pm

A perl class/module (projectSIGS.pm) that contains a class for each toplevel window/dialog, with skeleton signal handlers for any that were missing at build time. If the CWsplit style is used, the typical filename will be projectSIGS_class .pm (one file per class).

project.pm

A perl class/module (project.pm) that is a copy of projectSIGS.pm for you to edit to become your App. You can generate the UI again and again without changing any of your signal handlers as it is only written the first time through (if missing). If you add signal definitions to your Glade project, skeletons for the handlers will be generated in the projectSIGS.pm file and you can cut-and-paste them from there into the relevant class in the project.pm App module. If the CWsplit style is used, the typical filename will be project_class .pm (one file per class).

Subproject.pm

A perl class/module (Subproject.pm) that subclasses project.pm that you can edit to subclass your App. You can generate the UI again and again without changing any of your signal handlers as it is only written the first time through (if missing).

projectLIBGLADE.pm

An optional perl class/module (projectLIBGLADE.pm) that initialises the Libglade bindings and has skeleton signal handlers that you can edit to form your App. You can generate the UI again and again without changing any of your signal handlers as it is only written the first time through (if missing).

Glade::Run(3) glade2perl(1)

Documentation that came with the module is in Directory 'Documentation' in files README, Changelog, FAQ, FAQ.i18n, TODO, NEWS, ROADMAP etc.

The test file for CWmake test is test.pl which is runnable and has examples of user options.

A Perl script to generate source code from the Glade 'Build' button or menuitem is in file 'Example/glade2perl' and is installed when you CWmake install. You can also call this script from the command line.

A module that subclasses the test example is in file Example/SubBus.pm. This module will use (inherit or subclass) the generated perl classes and also use the supplied signal handlers module (Example/BusForm_mySUBS.pm)

Dermot Musgrove <dermot.musgrove@virgin.net>