NAME

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

SYNOPSIS

 use vars qw(@ISA);
 use Glade::App qw(:METHODS :VARS);
 @ISA = qw( Glade::App);

 # 1) CLASS methods
 my $Object = Glade::App->new(%params);
 $Object->glade->file($supplied_path);
 $widget = $window->lookup_widget('clist1');

 # 2) OPTIONS handling
 $options = Glade::App->options(%params);
 $normalised_value = Glade::App->normalise('True');
 $new_hash_ref = Glade::App->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::App->string_from_file('/path/to/file');
 Glade::App->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::App->load_translations('MyApp', 'fr', '/usr/local/share/locale/',
     undef, $SOURCE_LANG, 'Merge with already loaded translations');
 sprintf(_("A message '%s'"), $value);
 sprintf(gettext($SOURCE_LANG, "A message '%s'"), $value);
 Glade::App->start_checking_gettext_strings($SOURCE_LANG);
 Glade::App->stop_checking_gettext_strings($SOURCE_LANG);
 Glade::App->write_missing_gettext_strings($SOURCE_LANG);

 # 5) UI methods
 my $image = Glade::App->create_image('new.xpm', ['dir1', 'dir2']);
 my $pixmap = Glade::App->create_pixmap($form, 'new.xpm', ['dir1', 'dir2']);

 Glade::App->show_skeleton_message(
    $me, \@_, __PACKAGE__, "$Glade::App::pixmaps_directory/Logo.xpm");
 Glade::App->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::App->relative_Path($relative_path, $directory);

 $Object->reload_any_altered_modules;

DESCRIPTION

Glade::App 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::App and quotes Glade::App 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::App object

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

AUTOLOAD()

Accesses all class data

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

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::App->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::App->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::App->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::App->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, $hash_types)

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*');

SEE ALSO

Glade::Two::Generate(3) glade2perl-2(1)

AUTHOR

Dermot Musgrove <dermot.musgrove@virgin.net>