This is the Frequently Asked Question list for Glade-Perl source generator
--------------------------------------------------------------------------
Q   How do I see diagnostic messages when using glade2perl or from Glade?

A   Copy glade2perl and edit the 'verbose' line to read
        'verbose' => 2,     # for some diagnostics
        'verbose' => 4,     # for more diagnostics
        'verbose' => 6,     # for lots of diagnostics (more than you want ?)
        'verbose' => 10,    # for every diagnostic message available

    1)  Then either run Glade from a terminal, 
    2)  call the edited glade2perl directly (and maybe redirect STDOUT to a file)
    3)  specify a log_file in glade2perl if you want to save the diagnostics.
        'log_file' => $log_file, # Save diagnostics to Project.glade2perl.log
        This last option might be best, then all glade2perl runs will save the
        diagnostics to a file.
            
--------------------------------------------------------------------------
Q   How do I get the value of a GtkOptionMenu using Glade-Perl?

A   One way is to connect a handler to the 'hide' signal of the
    GtkOptionMenu's menu and then inspect the widget. eg. in a Gnome project
    called 'Reference' with 'optionmenu4' - edit the app_run() method in
    Reference.pm and write new on_optionmenu4_hide() to be:

    sub app_run {
        my ($class) = @_;
        $class->load_translations('Reference');
        # You can use the line below to load a test .mo file before it is
        # installed in the normal place 
        #     (eg /usr/local/share/locale//LC_MESSAGES/Reference.mo)
    #    $class->load_translations('Reference', 'test', undef, 
    #        '/home/dermot/Devel/Glade-Perl/Example/Reference/ppo/Reference.mo');
        Gnome->init('Reference', '0.53');
        my $window = $class->new;
        $window->TOPLEVEL->show;

        $window->FORM->{'optionmenu4'}->get_menu->signal_connect( 
            'hide', "$class\::on_optionmenu4_hide", '', 'optionmenu4', 
            $window->INSTANCE );

        Gtk->main;

    } # End of sub app_run

    sub on_optionmenu4_hide {
        my ($class, $data, $object, $instance, $event) = @_;
        my $me = __PACKAGE__."->on_optionmenu4_hide";
        # Get ref to hash of all widgets on our form
        my $form = $__PACKAGE__::all_forms->{$instance};

        my $selected_string = ($class->get_active->children)[0]->get;
        print "We have selected string $selected_string\n";

    } # End of sub on_optionmenu4_hide    

--------------------------------------------------------------------------
Q   Unicode::String 2.05 fails compilation under (default) Perl 5.6.0.

A   The maintainers have been notified and should fix this problem soon 
    (17 Apr 2000) but if you are brave you can amend String.xs as below
    
    It dies because PERL_POLLUTE is disabled by default in 5.6 which
    includes these two lines (from embedvar.h):
    
    #define na                    PL_na
    #define dowarn                PL_dowarn

    Adding those to the top of String.xs should cure any "'dowarn'
    undeclared/undefined  (first use in this function)" messages when
    compiling Unicode::String.

    Thanks to Jay J <linux@zeroink.com> for this temporary fix

--------------------------------------------------------------------------
Q   I wanted my real name and address in the files, so I added
      <author>Ren</author> 
    to the project xml file but when inspecting the generated files, I found
    # Copyright (c) Date Sat Apr  1 13:21:33 CEST 2000
    # Author Renf©
    Clearly glade2perl (or some module used herein) is doing something weird
    to the accented e in my name.

A   You guessed correctly - XML::Parser (which I use to read the options files
    as well as the Glade file) produces UTF8 encoded characters and these need
    to be converted from UTF8 to Latin1 in your case.

    Glade-Perl >= 0.53 should handle ISO-8859-1 characters correctly in both
    the Glade file and the project options files. If you want to use another
    encoding, you can edit Glade/PerlGenerate at or near line 76 to read:
        $Glade_Perl->{'options'}{'glade_encoding'} ||= 'ISO-8859-9';
    so that Glade-Perl will default to another encoding (see XML::Parser docs).
    
    You can also specify a user option (either in glade2perl or in the project 
    options file as 
      <glade2perl_encoding>ISO-8859-9</glade2perl_encoding> 
    to read the user options file as Latin9 characters.
    
    In Glade-Perl 0.52 there are some commented lines that you can uncomment
    to handle Latin1 characters.

    If you always want to use European characters there are some changes that
    you can make to Glade/PerlXML.pm so that your characters will be handled 
    correctly. This will also allow European characters in the UI.

    First download from CPAN and install perl module Unicode::String. 
    Then uncomment PerlXML.pm line 23 to use() the module
      use Unicode::String qw(utf8 latin1);    # To read ISO-8859-1 chars

    Comment out PerlXML line 181 and uncomment line 183
            # Comment out the line below if you are using european characters
    #        $np->{$self->[$count]} = $self->[$count+1][2];
            # Uncomment the line below if you are using european characters
            $np->{$self->[$count]} = &utf8($self->[$count+1][2])->latin1;
  
    I am working on a proper solution that will allow Glade-Perl to handle all
    character encodings and I would greatly appreciate any advice :)

--------------------------------------------------------------------------
Q   I use Solaris 2.6 and Ultra SPARC cpu, if I use the Gnome stock button, 
    why does it report a lot of error messages?

A   Install GNU grep (thanks to jacky.lu@ite.com.tw)

--------------------------------------------------------------------------
Q   How can I generate i18n apps?

A   Just generate the UI and app as normal :)

    If you want to gettext/translate strings in your signal handlers, surround 
    them with a call like '_("Your text to translate")' and they will be 
    translated when the app is run (if you have loaded a .mo file). You can
    edit the generated ProjectUI.pm file to specify a test .mo file but by
    default the app will look for a file called Project.mo (your project name)
    
    NB  The only difference with Glade-Perl gettext and the original C gettext 
        is that the empty string ('') is returned as '' and to get the .mo file 
        header information you must call _('__MO_HEADER_INFO'). 
        
        This stops widgets that are set to the empty string being translated 
        to the .mo header info :)
    
--------------------------------------------------------------------------
Q   How do I find out which strings to translate (put in the Project.pot file).

A   Make a directory (eg ppo) to keep all the i18n stuff together
    
    There are two easy ways to find out which strings to translate, otherwise
    you have to read through all the source and copy them.
    
    1)  First of all, check (set ON) the project option
        'Glade/User Option/LibGlade Options/Save Translatable Strings'
        Enter a filename in the 'File' to something eg ppo/xgettext.in and
        save the project.

        Use xgettext to generate a .pot (work) file for later editing by:
        xgettext -LC -ao ppo/Project.pot xgettext.in
    
    2)  Or insert 4 lines in your app (or uncomment them in the generated 
        subclass).

        i)  In the BEGIN sub insert the lines
              use Glade::PerlSource;
              @ISA = qw( Project Glade::PerlSource ); # use your project name

        ii) Just after you call     '$class->load_translations('Project');'
                (see FAQ   How do I test the translation file)
            insert the line         '$class->start_checking_gettext_strings;'

        iii)Just after you call     'Gtk->main;'
            insert the line         '$class->write_missing_gettext_strings;'
            
        Then when you run your app, go to every corner so that all the strings 
        get loaded. Any that are still missing from any loaded .mo file are 
        noted and written in .po format so that you can cut and paste them 
        from the run log or disk file into your work ppo/Project.pot file.

        You can call $class->stop_checking_gettext_strings; at any time to
        stop logging the strings.
        
        You can merge the new strings in ppo/Project.pot into any existing
        ppo/fr.pot file by calling 'msgmerge ppo/fr.pot ppo/Project.pot' 
        The order of the files is important - the first file gets updated.
        
--------------------------------------------------------------------------
Q   How do I make the ppo/fr.mo translation file

A   1)  copy ppo/Project.pot to file (eg ppo/fr.pot) and edit the translations
        Make sure that you have edited the all the strings in the header and 
        when you are ready to try it out remove the msgfmt directive line
          #, fuzzy
        from just above the header info at the top of the ppo/fr.po file 
        or the next step will fail (it means ignore the next definition).
        
    2)  When you want to try out the translations, copy ppo/fr.pot (temporary)
        to ppo/fr.po (final file) and use msgfmt to create a ppo/fr.mo file 
        for use by gettext by calling: msgfmt -o ppo/fr.mo ppo/fr.po
    
--------------------------------------------------------------------------
Q   How do I test the translation file

A   1)  You can edit the ProjectUI->run() sub or wherever you call Gtk->init;
        to specify your test src/fr.mo file with a line like:
        $class->load_translations('Project', 'test', undef, 
            '/path/to/your/ppo/fr.mo');
       
        Then run your program and see your UI in another language!
        Repeat the edit/test until you are happy with the translations.
           
    2)  Install /path/to/your/test/fr.mo to 
        /usr/local/share/locale/LC_MESSAGES/fr/Project.mo (or wherever)
    
        Set your $LANG env variable to a language that you have translated and
        run your app (after removing the testing line from ProjectUI->run or
        regenerating the UI and SIGS files).

--------------------------------------------------------------------------
Q   Why do I get message 'Can't locate object method "allow_grow" via package 
    "Gtk::Window" at Project3.pm line 115 (or similar)

A   This is caused by changes made to the CVS version of Gtk-Perl. Version
    0.45 will deal with this and other changes that have been made although
    there may be problems with earlier versions of Gtk-Perl :(
    The solution is to download and install Glade-Perl-0.45 (if you haven't
    already done so :)
        
--------------------------------------------------------------------------
Q   How do I set fonts, colours and bg-pixmaps of widgets at run time?

A   To change the fonts, colours and bg-pixmaps of widgets at run-time you can
    use something like the code below. This is for a button so it sets the 
    style of the button->child (in other words the label in the button) and the 
    actual way that you set the style will depend on what type of widget you are 
    working with. 
    
    There are many ways to get the colours but this is one approach:

    my $style = new Gtk::Style;
    my $cm = $form->{'button43'}->get_toplevel->window->get_colormap;

    $style->font(  Gtk::Gdk::Font->load(
        '-*-times-bold-r-normal-*-*-120-*-*-p-*-iso8859-1'));
    $style->fg('normal',   $cm->color_alloc(
        {red=>65000, green=>0,     blue=>0}));
    $style->fg('prelight', $cm->color_alloc(
        {red=>0,     green=>30000, blue=>0}));
    $style->fg('active',   $cm->color_alloc(
        {red=>0,     green=>0,     blue=>65000 }));

    $form->{'button43'}->child->set_style($style);

--------------------------------------------------------------------------
Q   Why doesn't Glade-Perl build my stock button correctly?
    If you run Glade-Perl with 'verbose' => 2 and STDOUT visible (on an xterm) 
    you will see a message like:
    warn  Gtk-Perl version 0.6123 cannot do 'GnomeStock' (properly) 
        we need CVS module 'gnome-perl' after 19990914

A   Your Gtk-Perl doesn't do Gnome::Stock->button. Perhaps you don't have
    the Gnome submodule built - in which case use labels instead.

    Gtk-Perl 0.6123 doesn't do Gnome::Stock->button at all. Either remove 
    the Stock Button property and use a label or upgrade to Gtk-Perl CVS 
    after 19990914 or version >= 0.7000.
    
--------------------------------------------------------------------------
Q   How do I write signal handlers in a separate module?

A   As always with Perl, there is more than one way to do it.

    1) The first way is to put your signal handlers in a .pm module and use() 
    the module from the generated source code. An example of this is the file
    '$DIST_DIR/Example/Bus/Bus_mySUBS.pm. You then specify this module to 
    Glade-Perl with the user option 'use_module' which you can check in the
    distributed script $DIST_DIR/test.pl. This is not the best approach as you
    have to make sure that you Export the signal_handler names if they are to
    run when you cause the signal.

    2) The better and simpler way is edit the generated Project.pm module and 
    put the signal handlers there. See $DIST_DIR/Example/Bus/Generated/Bus.pm.
    
    Glade-Perl >= 0.48 generates up to 4 perl files.
      A) ProjectUI.pm   - the UI constructor class (always written)
      B) ProjectSIGS.pm - utilities and skeleton signal handlers (always written)
      C) Project.pm     - a base for your app that you can safely edit
      D) SubProject.pm  - an example subclass of your app that you can edit

    3) Another way is to subclass the Bus.pm class and put your signal handlers 
    there. A skeleton subclass is generated in SubProject.pm and you can see a
    test example generated as $DIST_DIR/Example/Bus/Generated/SubBus.pm and 
    how to run it by looking at the test script $DIST_DIR/test.pl.
    
--------------------------------------------------------------------------
Q   How do I access widgets to set or get their data/text?

A   Each instance of a form (you can have more than one copy of a UI showing at
    the same time) stores a complete hash of its widgets in a global anonymous
    hash (actually defined as $Glade::PerlRun::all_forms) that you can access
    from your signal handler. One way to get at an entry widget in a signal
    handler is to look up the widget in this hash.

    The AUTOLOAD()ed signal handler message box shows all the args that would be
    passed to the relevant signal handler but something like this should work:

      sub my_signal_handler {
        my ($class, $data, $object, $instance) = @ARG;
        my $form = $__PACKAGE__::all_forms->{$instance};
        my $entry_val = $form->{'entry_widget_name'}->get_text;
        ...
     }

    This is for the case where the entry widget is on the same form as the 
    widget that causes the signal. In other cases you will have to store the 
    $instance value in a global or pass it as an arg somehow.

    Other unusual ways
    ------------------
    Glade-Perl versions >= 0.49 can generate up to 4 different types of
    hierarchical structure of widgets that can be traversed. The element names
    will change and I will add object methods so that the implementation can
    be changed without having to edit your code - but for now beware!
    This is very alpha but in general you specify a user option 'hierarchy':
    
    1) If the option includes 'widget' a structure is generated so you can call 
       $form->{'__WH'}{'vbox3'}{'frame2'}{'vbox1'}{'entry1'}{'__W'}->get_text;

    2) If the option includes 'class' a structure is generated so you can call 
       $form->{'__CH'}{'GtkVBox'}{'vbox3'}{'GtkFrame'}{'frame2'}
          {'GtkVBox'}{'vbox1'}{'GtkEntry'}{'entry1'}{'__W'}->get_text;
        This allows you to iterate over all widgets of a certain type in any
        one container - for instance.
        
    3) If the option includes 'order' a structure is generated so you can call 
       my $widget_array = $form->{'__WH'}{'vbox3'}{'frame2'}{'vbox1'}{'__C'};
       The array ref returned has the widgets in the order they were added to
       the VBox - in case you need to know :)
       
--------------------------------------------------------------------------
Q   My GtkClock does not show the current time

A   Older versions of gnome-libs (at least <= 1.0.8) do not handle the clock 
    type 'realtime' properly. Gtk-Perl 0.6123 cannot explicitly set the type 
    so we are stuck. Upgrade to a newer version of gnome-libs or Gtk-Perl.
        
--------------------------------------------------------------------------
Q   When I upgraded to Glade-Perl version 0.3.5 (or greater) I get error ...
    'Can't locate Gtk/Keysyms.pm in @INC (@INC contains: .....'
    
A   You have a flawed version of Gtk-Perl - eg released version 0.5121. There
    are many improvements in later versions (or in gnome.org CVS repository),
    for example, Glade-Perl now uses the new keysyms bindings in Gtk::Keysysms.
    Version 0.6123 is now available on CPAN (20 Aug 1999), otherwise you can
    get the CVS version ie. the 'gnome-perl' module in the CVS repository at 
    gnome.org and use that. There is a good description of the Gnome CVS on a
    Gnome mirror at http://www.uk.gnome.org/devel/whatiscvs.shtml
    
    If neither action is possible or desirable you can edit Glade::PerlUI.pm 
    in two places.
    
    change two lines in the Glade/PerlUI.pm module and 'make install' again

    #   use Gtk::Keysyms;               # comment out line 23 (or near)
    #   $self = $Gtk::Keysyms{$self};   # replace line 1590 (or near) 
                                        # by the line below
        $self = ord ($self );

    Of course, any keyboard accelerators that use keysyms other than A-Z,a-z
    will cause unusual behaviour but it should get you going.
    
--------------------------------------------------------------------------
Q   When I run glade2perl I get the following message ...
    Can't call method "merge_options" on an undefined value at
    /home/Perl/5.005_02/lib/site_perl/Glade/PerlProject.pm line 210.
    
A   Two people have reported this error, they use perl version 5.005_x with 
    some parts of perl installed in their home directory. I can't believe 
    that the problems come from perl but I don't know what else it could be,
    The error shown means that Glade::PerlGenerate->options has been called 
    without any arguments, not even a class name. 

    Eric Richardson <eric@gospelcom.net> found the problem! Thanks.
    It was caused by the use of @ARG to get at sub args. I still don't know 
    why this doesn't work with 5.005 but I have changed them all to the short 
    form of @_ in version 0.45 so this problem should not reappear.

--------------------------------------------------------------------------
