NAME

Glade::PerlRun - Utility methods for Glade-Perl (and generated applications).

SYNOPSIS

 use vars qw(@ISA);
 use Glade::PerlRun qw(:METHODS :VARS);
 @ISA = qw( Glade::PerlRun );
 # 1) CLASS methods
 my $Object = Glade::PerlRun->new(%params);
 $Object->glade->file($supplied_path);
 $widget = $window->lookup_widget('clist1');
 # 2) OPTIONS handling
 $options = Glade::PerlRun->options(%params);
 $normalised_value = Glade::PerlRun->normalise('True');
 $new_hash_ref = Glade::PerlRun->merge_into_hash_from(
      $to_hash_ref,      # Hash to be updated
      $from_hash_ref,    # Input data to be merged
      'set accessors');  # Any value will add AUTOLOAD() accessors
                         # for these keys.
 $Object->save_app_options($mru_filename);
 $Object->save_options;
 my $string = Glade::PerlRun->string_from_file('/path/to/file');
 Glade::PerlRun->save_file_from_string('/path/to/file', $string);
 # 3) Diagnostic message printing
 $Object->start_log('log_filename');
 $Object->diag_print(2, "This is a diagnostics message");
 $Object->diag_print(2, $hashref, "Prefix to message");
 $Object->stop_log;
 # 4) I18N
 Glade::PerlRun->load_translations('MyApp', 'fr', '/usr/local/share/locale/',
     undef, '__S', 'Merge with already loaded translations');
 sprintf(_("A message '%s'"), $value);
 sprintf(gettext('__S', "A message '%s'"), $value);
 Glade::PerlRun->start_checking_gettext_strings("__S");
 Glade::PerlRun->stop_checking_gettext_strings("__S");
 Glade::PerlRun->write_missing_gettext_strings('__S');
 # 5) UI methods
 my $image = Glade::PerlRun->create_image('new.xpm', ['dir1', 'dir2']);
 my $pixmap = Glade::PerlRun->create_pixmap($form, 'new.xpm', ['dir1', 'dir2']);
 Glade::PerlRun->show_skeleton_message(
    $me, \@_, __PACKAGE__, "$Glade::PerlRun::pixmaps_directory/Logo.xpm");
 Glade::PerlRun->message_box(
    $message,                               # Message to display
    $title,                                 # Dialog title string
    [_('Dismiss'), _("Quit")." Program"],   # Buttons to show
    1,                                      # Default button is 1st
    $pixmap,                                # pixmap filename
    [&dismiss, &quit],                      # Button click handlers
    $entry_needed);                         # Whether to show an entry
                                            # widget for user data
 # 6) General methods
 $path = $Object->full_Path($Object->glade->file, $dir);
 $path = Glade::PerlRun->relative_Path($relative_path, $directory);
 $Object->reload_any_altered_modules;

DESCRIPTION

Glade::PerlRun provides some utility methods that Glade-Perl modules and also the generated classes need to run. These methods can be inherited and called in any app that use()s Glade::PerlRun and quotes Glade::PerlRun in its @ISA array.

Broadly, the utilities are of seven types.

 1) Class methods
 2) Options handling
 3) Diagnostic message printing
 4) I18N
 5) UI methods
 6) General methods

1) CLASS METHODS

The class methods provide an object constructor and data accessors.

new(%params)
Construct a Glade::PerlRun object

e.g. my $Object = Glade::PerlRun->new(%params);

AUTOLOAD()
Accesses all class data

e.g. my $glade_filename = $Object->glade->file; or $Object->glade->file('path/to/glade/file');

lookup_widget($widgetname)
Accesses a window or a form's widget by name

e.g. my $widget = $window->lookup_widget('clist1');

  OR my $form = $window->FORM; # or use $form in signal handlers
     my $widget = $form->lookup_widget('clist1');

2) OPTIONS HANDLING METHODS

These methods will load, merge, reduce and save a hierarchical options structure that is stored in one or more XML files and accessed with AUTOLOAD methods.

options(%params)
Loads and merges all app options.

e.g. Glade::PerlRun->options(%params); my options = $Object->options(%params);

normalise($value)
Return a normalised value ie. convert 'True'|'Yes'|'y'|'On' to 1 and 'False'|'No'|'n'|'Off' to 0. The comparisons are case-insensitive.

e.g. my $normalised_value = Glade::PerlRun->normalise('True');

merge_into_hash_from($to_hash, $from_hash, $autoload)
Recursively merge a hash into an existing one - overwriting any keys with a defined value. It will also optionally set accessors for the keys to be used via AUTOLOAD().

e.g. $new_hash_ref = Glade::PerlRun->merge_into_hash_from( $to_hash_ref, # Hash to be updated $from_hash_ref, # Input data to be merged 'set accessors'); # Any value will add AUTOLOAD() accessors # for these keys.

save_app_options($mru, %defaults)
Updates mru and saves all app/user options. This will save the mru file in the user options file (if one is named in $class->{$class->type}->xml->user).

e.g. Glade::PerlRun->save_app_options($mru_filename);

save_options($filename, %app_defaults)
Reduce and save the supplied options to the file specified.

e.g. $Object->save_options;

write_options($options, $filename)
Write an options hash to XML file.

e.g. my options = $Object->write_options($hash_ref, '/path/to/file');

reduce_hash($all_options, $user_options, $site_options, $app_defaults, $base_defaults, $prune, $hashtypes)
Removes any options that are equivalent to site/user/project options or that are specified to be pruned. We will descend into any hash types specified.

e.g. my options = $Object->reduce_hash( $options_to_reduce, $user_options, $site_options, $app_defaults, $base_defaults '*work*proto*', '*My::Class*');

save_file_from_string($filename, $string)
Write a string to a file.

e.g. Glade::PerlRun->save_file_from_string('/path/to/file', $string);

3) DIAGNOSTIC MESSAGE METHODS

These methods will start logging diagnostic messages, produce standardised I18N messages and then stop logging and close any open files.

diag_print()
Prints diagnostics message (I18N translated) if verbosity is >= level specified

e.g. $Object->diag_print(2, ``This is a diagnostics message''); $Object->diag_print(2, $hashref, ``Prefix to message'');

start_log()
Opens the log files and starts writing diagnostics

e.g. $Object->start_log('log_filename');

stop_log()
Loads site/user/project/params options

e.g. $Object->stop_log;

4) INTERNATIONALISATION (I18N) METHODS

These methods will load translations, translate messages, check for any missing translations and write a .pot file containing these missing messages.

_()
Translate a string into our current language

e.g. sprintf(_(``A message '%s'''), $value);

gettext()
Translate into a preloaded language (eg '__S' or '__D')

e.g. sprintf(gettext('__S', "A message '%s'"), $value);

start_checking_gettext_strings()
Start checking and storing missing translations in language type 
  eg. $class->start_checking_gettext_strings("__S");

stop_checking_gettext_strings()
Stop checking for missing translations in language type 
  eg. $class->stop_checking_gettext_strings("__S");

write_missing_gettext_strings()
Write a .pot file containing any untranslated strings in language type 
  eg. $object->write_missing_gettext_strings('__S');

load_translations()
Load a translation file (.mo) for later use as language type 
  e.g. To load translations in current LANG from default locations
        $class->load_translations('MyApp');


  OR    $class->load_translations('MyApp', 'test', undef, 
            '/home/dermot/Devel/Glade-Perl/ppo/en.mo');
  OR    $class->load_translations('MyApp', 'fr', '/usr/local/share/locale/',
           undef, '__D', 'Merge with already loaded translations');

5) UI METHODS

These methods will provide some useful UI methods to load pixmaps and images and show message boxes of various types.

create_pixmap()
Create a gdk_pixmap and return it

e.g. my $pixmap = Glade::PerlRun->create_pixmap( $form, 'new.xpm', ['dir1', 'dir2']);

create_image()
Create and load a gdk_imlibimage and return it

e.g. my $image = Glade::PerlRun->create_image( 'new.xpm', ['dir1', 'dir2']);

show_skeleton_message($class, $caller, $data, $package, $pixmap)
This method pops up a message_box to prove that a stub has been called. It shows a pixmap (logo) and buttons to dismiss the box or quit the app 
 $caller    where we were called
 $data      the args that were supplied to the caller
 $package
 $pixmap    pixmap to show

e.g. Glade::PerlRun->show_skeleton_message( $me, \@_, __PACKAGE__, ``$Glade::PerlRun::pixmaps_directory/Logo.xpm'');

message_box()
Show a message box with optional pixmap and entry widget. After the dialog is closed, the data entered will be in global $Glade::PerlRun::data.

e.g. Glade::PerlRun->message_box( $message, # Message to display $title, # Dialog title string [_('Dismiss'), _(``Quit'').`` Program''], # Buttons to show 1, # Default button is 1st $pixmap, # pixmap filename [&dismiss, &quit], # Button click handlers $entry_needed); # Whether to show an entry # widget for user data

6) GENERAL METHODS

These are some general purpose methods that are useful to Glade::PerlGenerate and generated apps.

full_Path()
Turn a relative path name into an absolute path

e.g. my $path = Glade::PerlRun->full_Path($relative_path, $directory);

relative_Path($basepath, $path, $root)
Turn an absolute path name into a relative path

e.g. my $path = Glade::PerlRun->relative_Path($relative_path, $directory);

string_from_File()
Reads (slurps) a file into a string

e.g. my $string = Glade::PerlRun->string_from_file('/path/to/file');

reload_any_altered_modules()
Check all loaded modules and reload any that have been altered since the app started. This saves restarting the app for every change to the signal handlers or support modules.

It is impossible to reload the UI module (called something like ProjectUI.pm) while the app is running without crashing it so don't run glade2perl and then call this method. Similarly, any modules that construct objects in their own namespace will cause unpredictable failures.

I usually call this in a button's signal handler so that I can edit the modules and easily reload the edited versions of modules.

e.g. Glade::PerlRun->reload_any_altered_modules;

SEE ALSO

Glade::PerlGenerate(3) glade2perl(1)

AUTHOR

Dermot Musgrove <dermot.musgrove@virgin.net>